rest2web-develop

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

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

[Peter TB B. <pe...@pe...>]

fuz...@vo... wrote:

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

...but it would be a very, *very*, **very** useful feature.

Peter ;)


--
Quake II build tools: http://peter-b.co.uk/
Latest QuArK:         http://quark.sourceforge.net/LatestVersion

v2sw6YShw7ln5pr6ck3ma8u7Lw3+2m0l7CFi6e4+8t4Eb8Aen4g6Pa2Xs5MSr5p4
  hackerkey.com

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

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

Peter TB Brett wrote:

>fuz...@vo... wrote:
>
>  
>
>>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).
>>    
>>
>
>...but it would be a very, *very*, **very** useful feature.
>
>  
>
The only way to do it would be to make rest2web a two pass process. In
the first pass build all the structures (which includes contents
information).

In the second pass build the pages. This means every page would have
access to the information about all the other pages. This would allow
some funky collapsing javascript indexes, showing the entire site structure.

It would also be a good opportunity to implement a nice caching
mechanism that only has to parse/rebuild pages that have changed (or
where the templates have changed).

This wouldn't actually be *that* big a deal to implement. Extracting
contents information from docutils (by accessing the data structure
created by the ``.. contents::`` directive) would be *interesting* - but
probably achievable. What to do with html pages, or pages that don't use
``.. contents::`` is another question.

It still leaves the 'index' question unsolved, building a contents page
is one thing. Marking items for inclusion in an index is something else
I would like to do, but am not sure how (macro with global data
structure ?).

Also - as a single developer (hint!) this will have to fit in with the
other projects I'm working on.

I'm currently working on :

* New version of Movable Python - might generate some income so a high
priority
* New release of the guestbook which includes the akismet anti-spam
* New *version* of the guestbook with web admin interface for easy
deletion/editing of entries
* Release of skimpy the Python search engine

So.... it rest2web will have to fit in with these. :-)

The rest2web source code is very well commented if you fancy having a
poke around inside.

Seasons greetings...

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

>Peter ;)
>
>
>--
>Quake II build tools: http://peter-b.co.uk/
>Latest QuArK:         http://quark.sourceforge.net/LatestVersion
>
>v2sw6YShw7ln5pr6ck3ma8u7Lw3+2m0l7CFi6e4+8t4Eb8Aen4g6Pa2Xs5MSr5p4
>  hackerkey.com
>
>
>
>-------------------------------------------------------
>This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
>for problems?  Stop!  Download the new AJAX search engine that makes
>searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
>http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click
>_______________________________________________
>Rest2web-develop mailing list
>Res...@li...
>https://lists.sourceforge.net/lists/listinfo/rest2web-develop
>
>  
>