On 2009-08-29, Timmie <timmichel...@gmx-topmail.de> wrote:
>
> Dear Sphinx developers,
> I have encountered some issues with the autosummary extension.
> I like that extension a lot and it has improved well.
>
> Please have a look here:
> * autosummary: generated stub files are not re-written -
> http://bitbucket.org/birkenfeld/sphinx/issue/247/autosummary-generated-stub-files-are-not-re
> * autosummary: template improvement -
> http://bitbucket.org/birkenfeld/sphinx/issue/249/autosummary-template-improvement
> * autosummary: option for all modules of a package -
> http://bitbucket.org/birkenfeld/sphinx/issue/248/autosummary-option-for-all-modules-of-a
> * autosummary: generated stub files are not re-written -
> http://bitbucket.org/birkenfeld/sphinx/issue/247/autosummary-generated-stub-files-are-not-re
>
> Are these valid bugs / feature request or just wrong configurations on
> my side?
I think you are trying to use the autosummary extension to build
Epydoc-like features into Sphinx: automatic documentation
generation for a whole Python package.
This is not really what the extension was written for: the main
purpose was to replace the output from multiple consequent
auto*:: directives with a table that has links to separate pages
each containing the output from one directive. I'm not sure the
documentation for the directive currently explains this aim
clearly enough.
In fact, as you found out, it is possible to do this already to
some degree by adding :toctree: options to the default templates,
thanks to the recursive generation feature.
However, one hurdle in making automatic doc generation work well
is handling of names pointing to the same objects. This isn't
currently implemented at all in autosummary::, and adding it
would probably require some major reworking of how things work
currently.
Personally, I'm at the moment not very convinced that extending
the directive to allow more extensive automated document
generation is a good idea: I think the work that goes in manually
writing most of the .rst files pays back in ensuring that things
form a logical picture, rather than a dump of names and
descriptions in alphabetical order.
--
Pauli Virtanen
--~--~---------~--~----~------------~-------~--~----~
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
sphinx-dev+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
