[Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code

[Felix Wiemann]

Michael Hudson wrote:

> Michael Foord <mike at pcblokes.com> writes:
>
>> A brief but resounding +1 to the idea of standardising Python doc
>> generation using docutils.
>
> Are you talking about the existing Python documentation?  Or just a
> way of making the "blue arrows" HTML from ReST?

I think there's no need to make blue arrows from reST (yet).  The first
step to do would be to have a way to generate LaTeX code suitable for
the current tool-chain.

> The issue with the existing documentation is that it exists, and in
> latex...

Since the LaTeX code is quite well-structured, I suppose it's possible
to convert it to reST.  But that's at least one step too early now.

First thing to do is implementing directive- and role-equivalents for
all macros described at
<http://docs.python.org/doc/special-constructs.html>.

And maybe we could use a standard way of passing multiple parameters to
a role (see <http://docs.python.org/doc/inline-markup.html> for examples
of where that's needed).  However, the (probably better) alternative to
a unified way of passing multiple parameters is to have the role handler
code do its own individual parsing, e.g.

    :versionchanged:`2.4: New flag XY.`

for the two parameters ``2.4`` and ``New flag XY.`` (separated by ": "),
and

    :manpage:`latex(1)`

for ``latex`` and ``1``.

Both roles take multiple parameters, but they have different ways of
separating them.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/