Hi all, There is a very interesting discussion and python-dev and Doc-SIG about using reST to document python. I think that the ongoing effort to document numpy and friends with reST could benefit from interaction with these guys. Gaël ----- Forwarded message from Georg Brandl <g.brandl@gmx.net> ----- To: Doc-Sig@python.org From: Georg Brandl <g.brandl@gmx.net> Date: Sat, 19 May 2007 19:14:09 +0200 Cc: python-dev@python.org Subject: [Doc-SIG] The docs, reloaded Hi, over the last few weeks I've hacked on a new approach to Python's documentation. As Python already has an excellent documentation framework, the docutils, with a readable yet extendable markup format, reST, I thought that it should be possible to use those instead of the current LaTeX->latex2html toolchain. For the impatient: the result can be seen at <http://pydoc.gbrandl.de>. I've written a converter tool that handles most of the LaTeX markup and turns it into reST, as well as a builder tool that adds many custom directives and roles, and also features like index generation and cross-document linking. (What you can see at the URL is a completely statical version of the docs, as it would be shipped with the distribution. For the real online docs, I have more plans; I'll come to that later.) So why the effort? Here's a partial list of things that have already been improved: - the source is much more readable (for examples, try the "view source" links in the left navbar) - all function/class/module names are properly cross-referenced - the HTML pages are generated from templates, using a language similar to Django's template language - Python and C code snippets are syntax highlighted - for the offline version, there's a JavaScript enabled search function - the index is generated over all the documentation, making it easier to find stuff you need - the toolchain is pure Python, therefore can easily be shipped What more? If there is support for this approach, I have plans for things that can be added to the online version: - a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would redirect you to the matching location. - "interactive patching": provide an "propose edit" link, leading to a Wiki-like page where you can edit the source. From the result, a diff is generated, which can be accepted, edited or rejected by the development team. This is even more straightforward than plain old comments. - the same infrastructure could be used for developers, with automatic checkin into subversion. - of course, plain old comments can be useful too. Concluding, a small caveat: The conversion/build tools are, of course, not complete yet. There are a number of XXX comments in the text, most of them indicate that the converter could not handle a situation -- that would have to be corrected once after conversion is done. Waiting for comments! Cheers, Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig ----- End forwarded message ----- -- Gael Varoquaux, Groupe d'optique atomique, Laboratoire Charles Fabry de l'Institut d'Optique Campus Polytechnique, RD 128 91127 Palaiseau cedex FRANCE Tel : 33 (0) 1 64 53 33 49 - Fax : 33 (0) 1 64 53 31 01 Labs: 33 (0) 1 64 53 33 63 - 33 (0) 1 64 53 33 62