Hi, On Sat, Oct 3, 2009 at 2:13 PM, Oben <obenso...@googlemail.com> wrote: > 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.
I'm also a bit puzzled by this, and I think we'd greatly benefit from wider adoption of real reST for all docstrings, including in the stdlib (honestly the state of docstrings in the stlib is atrocious for the most part, so almost anything there will be an improvement). The numpy/scipy projects adopted what I think is a very sensible docstring standard, basically plain reST with some conventions, and so far the nipy family of projects and ipython at least have also adopted it: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This lets you write simple docstrings like the one in the example: http://svn.scipy.org/svn/numpy/trunk/doc/example.py To parse these you need an extension, which is available with numpy as well: http://projects.scipy.org/numpy/browser/trunk/doc/sphinxext/numpydoc.py Since I personally do like fully automatic API coverage (in addition to well-written, humanly tuned docs), in nipy we have a little API generator that you are welcome to grab. It's two files, a short script you tailor to your project and the module that does the real work, that should be completely project-independent: http://bazaar.launchpad.net/~nipy-developers/nipy/trunk/annotate/head%3A/tools/build_modref_templates.py http://bazaar.launchpad.net/~nipy-developers/nipy/trunk/annotate/head%3A/tools/apigen.py It's used by a little bit of code in the 'api' rule of the makefile: http://bazaar.launchpad.net/~nipy-developers/nipy/trunk/annotate/head%3A/doc/Makefile I've posted this here before and others have found it useful, it lets a project produce full API docs automatically. With numpy markup in the docstrings, they are very readable in raw text (such as with ipython's foo?) and yet they produce quite civilized html/pdf in the end, e.g: http://nipy.sourceforge.net/nipy/api/generated/nipy.algorithms.statistics.rft.html The numpy doc standard may not be perfect, but many of us find that it's a very good compromise between plaintext readability and final doc generation quality (the :param: style of docstring is very annoying for users to read in plaintext). HTH, f --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
