Thanks for the hints (unfortunately berlios.de seems to be down right now). However, a better solution would be to have an extension which integrates sections in docstrings into the final TOC. Maybe one day I'll have some time to work on this .. and maybe until then someone else has done this already ;)
But seriously, if reST and Sphinx are supposed to be the standard for Python documentation, isn't backwards to force shifting API documentation out of the docstrings? AFAIK the official Python documentation is written mostly outside the source code and I see the benefits of this approach as it avoids API generator look-a-like documentation. OTH I would guess many projects in the Python world are happy with simple API generation, consider the JavaDoc workflow as an example. Well, there are tools like epydoc but I would prefer to follow the "official" Python documentation conventions and tools. I'm quite surprised Sphinx does not spend much attention to straightforward API doc generation. On Oct 3, 10:28 pm, Pauli Virtanen <[email protected]> wrote: > la, 2009-10-03 kello 20:14 +0000, Guenter Milde kirjoitti: > > > On 2009-10-03, Oben wrote: > > > > In my workflow I really prefer to have all documentation in the source > > > file and thus would benefit from sections in docstrings. > > > You might consider using PyLit (http://pylit.berlios.de). > > Another option is to use the autodoc-process-docstring hook [1], and > mangle all sections to ".. rubric::", except for automodule::. This of > course loses TOC information. > > .. [1]http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing > > -- > 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 [email protected] 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 -~----------~----~----~----~------~----~------~--~---
