Just a quick note: I've looked at the repo, and I'll go over the code soon. I don't want to add the whole thing to 0.5 -- that will be out soon and has already enough new features. Instead, we can let autosummary mature, and include it in 0.6 (which won't be as long as 0.5 was from 0.4, I promise).
cheers, Georg percious schrieb: >> 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. --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
