[Python-Dev] [Doc-SIG] The docs, reloaded

[Lea Wiemann]

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