[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>
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
