[Python-Dev] [Doc-SIG] The docs, reloaded (original) (raw)

Lea Wiemann lewiemann at vassar.edu
Sun May 20 10:04:24 CEST 2007

Martin Blais wrote:

e.g. are you still marking classes as classes and functions as functions in the ReST source

It seems so (modulo XXX's and TODO's in Georg's implementation, probably ^_^) -- all of the pages have "show source" links, so you can see for yourself. I'm not an expert with the documentation system, but the markup on <http://pydoc.gbrandl.de/modules/codecs.txt> looks pretty complete to me.

(Somewhat related, but another idea from back then, which was never implemented IMO, was to find a way to automatically pull and convert the docstrings from the source code into the documentation, thus unifying all the information in one place.)

While it's probably not possible to simply generate the documentation from the docstrings, it would certainly seem interesting to get have some means (like a directive) to pull docstrings into the documentation. I think however that while migrating the docs do reStructuredText is comparatively straightforward [1]_, pulling documentation from the docstrings will require quite a bit of design and discussion work. So I'd suggest we postpone this idea until we have a working documentation system in reStructuredText, so we don't clutter the discussion.

.. [1] I'm sure there will still be quite a few issues to sort out that I'm simply not seeing right now.

Best wishes,

Lea

More information about the Python-Dev mailing list