> Sphinx autodoc has 'signals' that the user can hook into, to mangle the > docstrings and function signatures before autodoc processes them. This is > useful if the docstring format is not native Sphinx format, or if > Sphinx's function signature introspection fails and the user has some > alternative way to find the signature. > > Internally, sphinx.ext.autodoc calls these user-provided functions, > through its signal mechanism. (Look for 'emit' in autodoc.py) > > Since autosummary needs to display probably at least a list of function > summaries, it would be useful for the user to have control over this. For > example, in Numpy the first docstring line might not be a function > summary, but a function signature (if the function happens to be from a C > extension -- for these automatic signature introspection doesn't work), > so we have custom functions attached to the two hooks to make Sphinx > understand us. If this would at the same time work for the future > autosummary, even better.
Thanks for the in-depth explanation paul! I want to keep the default for autosummary as close to the autodoc default as possible, whilst providing those options for function summaries, signatures, and other things we have yet to discover. My feeling was that numpy code has a very specific format which other projects may/may not use, but providing a good way for user's to hook in their own style of formatting would be a good thing. My hope was to take what numpyext was doing, generalize it, and then build back up to the point where the numpy docs look appropriate. You bring up a good point about the c-extensions, and I would like to support that too. I am still learning the details of the numpyext implemenmtation, and hoping that I will be able to add these bits in an intelligible way. > >> - I'd recommend retaining the signature formatting functionality -- > >> it's > >> probably generally useful. Though maybe the function signatures > >> shouldn't be on by default. > > > I have been debating this a bit, and I think the "right" way to handle > > this is to add it as a feature for sphinx-autodoc. For the default > > autosummary, i want to just provide links for the user to click. I > > think the "right" way to handle this is to provide a "sub" directive to > > autosummary called :signature: or something, similar to how :autoclass: > > works. > > Directives can take options, eg. > > .. autosummary:: > :show-signatures: > > func1 > func2 > ... > > Actually, there's already a :no-signature: option defined there, IIRC. > And yes, it probably is possible to call directly into sphinx.ext.autodoc > and let it sort out the function signatures etc. If it can't easily do > this, I'd believe it can be refactored a bit. > Yes, so I'd like to make something like :show-signatures: work right. That'll probably be my first priority. > > Let me know if you want the "push" bit ;-). I miss saying "commit bit", > > maybe we should compromise and call it the push bush? Nah... > > We can as well go DVCSsy, I branch in bitbucket and put in a pull request > when I have something to chip in. Many eyes probably result to better > code. > > Cheers, > Pauli Pull requests are the "new way". I rather like it. cheers. -chris --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
