Tue, 04 Nov 2008 14:07:32 -0800, percious wrote:
> Thanks for finding that bug Paul!
>
> And yes, there is a ton of functionality in the Numpy stuff. I wanted a
> good base to build from, and a clean slate to pull in intelligible numpy
> stuff.
>
>> - Hooking autosummary into the same "autodoc-process-docstring"
>> and "autodoc-process-signature" signal as sphinx.ext.autodoc would
>> be nice.
>
> Can you explain what you mean a little more by this.
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.
>> - 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.
>> - There's presently an error on line 222 in autosummary/__init__.py,
>> variable "title" is undefined, but maybe this part is still under
>> refactoring.
>
> fixed.
>
> 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
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
