-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Oben schrieb: > 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.
Well, Sphinx was never intended to be "the official documentation standard" for all Python world. It was created to be the successor to the LaTeX based toolchain the old Python docs were written for, and since that wasn't used extensively by other projects, I didn't assume Sphinx to become so popular either. The Python docs have never used any docstring extraction, all content is in the source files. Docstrings have always been maintained separately. While this is a lot of extra burden on the maintainers, it ensures that both docstrings and the docs have the "right amount" of content; i.e. docstrings are concise and only cover very important special cases, the docs are much more in-detail and can also digress in places. (There are some people who'd like to change that situation in Python, mainly because they're seeing how it is comparatively easy to integrate docstrings into a still separately written body of documentation. I'm not sure we'll ever make that change, but it is a possibility. That something needs to be done about many modules' docstrings is unquestioned though.) So much for history... it explains why automatic generation of content was not planned in Sphinx from the beginning. After a while I understood the need for more and more automatic features, and added autodoc, autosummary, etc. A full API doc generation may be inevitable :) In that, I'm glad for any help -- there are just so many different ways it could be done. Georg -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.11 (GNU/Linux) iEYEARECAAYFAkr3EJsACgkQN9GcIYhpnLBkIQCeKJu23CuOyxxQgkP9K0i7/Yt3 qDcAoJRGW72deq6r/azJPcoB7xJY5mK8 =ivcm -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
