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

[Felix Wiemann]

Martin Blais wrote:

> 1. writing python documentation using docutils, is it possible?

Not currently.

> here's a cool idea, i don't know if it's been discussed here before,

Not that I know of.

> but do you think it would be possible to add docutils directives for
> all the markup that the python documentation requires?  ( in
> particular, there could be directives to automatically extract much of
> the information from the python declaratoins themselves, using
> inspection ) e.g.
>
> .. funcdesc:: foo( param1, param2=True )
>
> would automatically parse the function declaration and generate
> appropriate output.

Looks nice.  +1.

> a sort of specialized rest input (just some directives really) with
> specialise latex output.  we could even output using the current LaTeX
> macros that the python docs are currently using...

That's a must-have, indeed, otherwise Docutils won't be able to generate
genuine Python documentation.  (Let's not talk about moving the whole
Python documentation system to Docutils; that's too far in the future.)

> 2. unifying source code and readable documentation

I'm not sure if we want that because source documentation is for
developers and external documentation is for users, but it's certainly
worth thinking about.

> [...] it seems to me that auto-generated documentation tools should
> really be part of python.

Docutils will be ready at the earliest in a few years.  Dunno about
Epydoc though.

> we might want to do something to couple the source code and the
> written manual, e.g. where we could have a template that outlines the
> "manual" versoin of the documentation, and our directive would go
> fetch the docstring for the function or class and insert it inline in
> our document automatically.  a class documentation could look like
> this:
>
>  intro and example text
>  .. classdescref:: module.classname
>  ..methoddescref:: module.classname.foo1
>  ..methoddescref:: module.classname.foo2
>  ..methoddescref:: module.classname.foo3
>  ..methoddescref:: module.classname.foo4
>
> this would allow arbitraty ordering of the methods (something which an
> automated source to docs tool couldn't do)

No, let's pick up the methods automatically.  The methods *can* be
reordered by just moving them around.

> also, one thing that i can't see is how to generate index entries from
> docutils.  also, for typed references e.g. \function{foo}, i don't
> know how you would do that in docutils.

::

    .. role:: function

    :function:`foo`

In the stylesheet for the new LaTeX writer which I'm currently
developing::

    \providecommand{\DCfunction}[2]{\function{#2}}

I have a deadline next Wednesday, so I'll probably upload the new LaTeX
writer then.

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

http://www.ososo.de/