[Python-Dev] The docs, reloaded

[Ron Adam]

Georg Brandl wrote:
> 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>.

Wow, very nice.  I like it.. +1

I've been working on improving pydoc. (slowly but steadily) Maybe we can 
join efforts as I think the two projects overlap in a number of areas, and 
it sounds like we are thinking of some of the same things as far as the 
tool chain.  So maybe there's some synergy we can take advantage of.

Some of the things I've recently considered adding to pydoc.

    - To output individual sections for use in a template engine.
    - A reST formatter.
    - Use docutils to format reST doc strings to html in the html
        formatter.  (as an option, not the default.)

It looks like there may be a few areas where we can share code.

    - The html syntax highlighters.   (Pydoc can use those)
    - A shared html style sheet.
    - Document locater.  [1]
    - An HTMLServer for local (dynamic dispatching) html viewing. [2]
    - The reST source for viewing topics and keywords in pydoc.
          (Instead of scraping html pages. Ick)

(1.) Pydoc has a locater function which finds the html docs and presents a 
link to the html page for an individual item.  But it would be more 
reliable if the dispatcher where on the document end.  Then pydoc would 
have a single place to link to.  (Either locally or on line.)

(2.) The server in pydoc will probably work as is.  You just need to supply 
a callback to get the pages.  It's a separate module now.

Cheers,
    Ron


> 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