[Rest2web-develop] Python(like) Documentation in reST

[<fuz...@vo...>]

{acro;html} I like the `reST <http://docutils.sourceforge.net>`_ plain text markup format. You might guess that from my `rest2web <http://www.voidspace.org.uk/python/rest2web/>`_ project, which allows me to maintain my website in {acro;reST;reStructuredText} [#]_.

There has been some discussion about developing the Python documentation in reST. Unfortunately it seems that reST, as a plain-text format, is unlikely to ever develop the complexity needed to replace LayTeX as the python documentation format [#]_.

That aside, it would still be nice to have a tool that built docs that *look* like the Python documentation from reST sources. The Python documentation is very attractive, and the '**Next**', '**Previous**, and '**Up**' blue arrows make them very usable as well.

`rest2web`_ now has a way of specifying page order in a directory (and section) - the ``section-pages`` keyword in the `restindex </python/rest2web/restindex.html>`_.

It occurs to me that this means it should be easy enough to provide each page with links to it's  '**Next**', '**Previous**, and '**Up**' pages within it's namespace.

If I can extract the page contents from docutils (I have some example code to do this), then it should be possible to autobuild full contents pages for a directory as well. 
Unfortunately, splitting larger documents down into several pages is probably beyond me (until docutils provides a way of doing it anyway).

This means that it would be possible to create Python-like documentation using **rest2web**. The only limtiation is that site are built *top down*, so directories wouldn't have easy access to the contents of directories below them. Building large contents pages that include subdirectories wouldn't be possible (yet).

.. [#] It also allows you to keep content as {acro;HTML}, so it can be used as a templating system (that will autobuild index pages) for *any website* - without requiring you to use **reST**.
.. [#] Specifically, a syntax to mark functions and arguments *and* build indexes from this data, is required.