[Doc-SIG] regarding the current state of Python docs

[Fredrik Lundh]

John M. Gabriele wrote:

> I've just joined this list, and judging from some of the
> posts I've seen in the archives, there seems to be some
> concern about a problem with the current way Python is
> documented.
>
> My guess is that the current system looks something like
> this:
>
> 1. checkout the doc source
> 2. make changes
> 3. commit changes

it's actually more like (quoting from an earlier post):

    If logged in to a machine with a full Python development environment:

    1) sync the project
    2) locate the right source file
    3) edit, and save to disk
    4) (optionally) regenerate the documentation and inspect it (3-6 minutes
        if you have the toolchain installed)
    5) commit the change (alternatively, generate a patch)
    6) wait up to 12 hours for the updated text to appear on the developer
       staging area on python.org, and 3-6 months for the next documentation
       release to appear on the site

    If no access to a Python development environment:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) write note or mail to self (or generate a patch)
    3) at an unspecified later time, try to remember what you did, and follow
       the developer instructions above.  wait 3-6 months for the next doc
       release to appear on the site.

> Personally, I think the best way document Python (outside
> of the built-in docstrings) is a wiki but with only a select
> group of folks with edit privileges.

Absolutely, but we want good semantic markup, and no wiki format I've
seen makes it easy to get the semantics right.  That doesn't mean that
we cannot use an existing wiki engine, but I don't think any existing wiki
format will cut it.

> How hard is it to convert html to suitable moinmoin wiki
> text input? Is there already a tool for this? Maybe someone
> needs to just jump on it, pull the starter on the chainsaw,
> just go for it, and let the chips fall where they may. :)

I've spent a week hacking away with a small axe in my spare spare time:

    http://effbot.org/zone/pyref.htm
    http://effbot.org/lib/ (output snapshots)
    http://online.effbot.org/ (look for documentation posts)

if some wiki engine and/or python framework hacker wants to start playing
with an edit-through-the-web frontend for the new structured documentation
format, drop me a line.  ajax and css tinkerers are also welcome.

</F>