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

[David Goodger]

[Martin Blais]
> 1. writing python documentation using docutils, is it possible?
>
> here's a cool idea, i don't know if it's been discussed here before,

Yes, it's possible (or should/will be), and it has been discussed :-)
Some work has already been done.  I summarized it here:
http://docutils.sf.net/sandbox/README.html#documenting-python

> but do you think it would be possible to add docutils directives for
> all the markup that the python documentation requires?

Yes.

> ( in particular, there could be directives to automatically extract
> much of the information from the python declaratoins themselves,
> using inspection )

That's a different issue: auto-documentation.  Documented here:

http://docutils.sf.net/docs/peps/pep-0258.html#python-source-reader
http://docutils.sf.net/docs/dev/pysource.html
http://docutils.sf.net/docs/dev/todo.html#python-source-reader

The two issues should be dealt with separately.

> 2. unifying source code and readable documentation

This is a debate that's been going on for a long time.  I'm not going
to get into it again :-)

> 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.

You're talking about "literate programming":
http://www.literateprogramming.com/

> also, one thing that i can't see is how to generate index entries
> from docutils.

Hasn't been implemented yet, but there are ideas:
http://docutils.sf.net/docs/dev/rst/alternatives.html#index-entries-indexes

> also, for typed references e.g. \function{foo}, i don't
> know how you would do that in docutils.

:function:`foo`

> anyway, that's a bit of a quick trigger email, maybe i should do more
> due diligence to find out if that's been considered in the past...

Um, yeah ;-)

But there's a lot of work to be done, decisions to be made, issues to
be thought out.

--
David Goodger <http://python.net/~goodger>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 253 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/doc-sig/attachments/20050423/0436145a/signature.pgp