[Python-Dev] The docs, reloaded

[Steven Bethard]

On 5/19/07, Georg Brandl <g.brandl at gmx.net> wrote:
> For the impatient: the result can be seen at <http://pydoc.gbrandl.de>.
[snip]
> 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

Very cool!  I'd love to see the docs move to ReST.

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

Yes, these would all be outstanding features.

STeVe
-- 
I'm not *in*-sane. Indeed, I am so far *out* of sane that you appear a
tiny blip on the distant coast of sanity.
        --- Bucky Katt, Get Fuzzy