regarding the current state of Python docs

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

regarding the current state of Python docs

John M. Gabriele
Hi,

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


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. That is, only after
you've been around for a little while (or otherwise shown
that you can write good docs and want to help) are you given
edit access. Nothing too strict. Just limited to folks who
actually want to help, and who can show they're fairly
good at it. The same way you grant committer access on any
free software project.

It seems like it wouldn't *too* be much trouble to simply
take all the docs as they currently are and export them to
a new wiki, wholesale. That is, create a "sister" wiki to
the one we already have. Put the whole enchilada on there.
The library reference, the language reference. Everything.

Editing a wiki page is *way* easier than doing the checkout-
edit-commit procedure as outlined above. Sometimes I've only
got 5 or 10 minutes, and really would like to see a small
clarification in the docs. If it were wikified, I could
make that change (say, on my slashdo^H^H^H lunch break).
If I'm at work, and had to do a checkout, etc, ... no way
would I bother. It would have to wait 'til I get home -- then
with the wife and kids wanting some family time, the edits
might not even happen.

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

---J


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: 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>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: regarding the current state of Python docs

John M. Gabriele


--- Fredrik Lundh <[hidden email]> wrote:

> John M. Gabriele wrote:
>[snip]
>
> > 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.

I've only poked around a little bit so far, but it looks
like the python wiki of choice seems to be moinmoin.

What sort of output are you looking for that moinmoin
cannot provide? Just curious. Lots of sites use plain
wiki software for their docs, and I've always found
them to be satisfactory.

Perhaps there's a plug-in of some sort for that wiki
that will give you what you're looking for? Maybe
more info here:
http://moinmoin.wikiwikiweb.de/MoinMoinExtensions


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

So, I'm not quite sure what I'm looking at there. Have
you been taking the doc source (LaTeX) and converting it
to input suitable for moinmoin, or are you writing your own
wiki engine with its own markup style? I mean this as a
compliment: those links point to pages that look pretty
much like normal wiki pages. :)

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

What's "the new documentation format"?


>  ajax and css tinkerers are also welcome.
>
> </F>
>

Thanks,
---J


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: regarding the current state of Python docs

Fredrik Lundh
John M. Gabriele wrote:

>> 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)
>
> So, I'm not quite sure what I'm looking at there. Have
> you been taking the doc source (LaTeX) and converting it
> to input suitable for moinmoin, or are you writing your own
> wiki engine with its own markup style?

I prefer to model things as a collection of components, and leave the
overall architecture open for as long as possible.  The links above dis-
cusses converters, a reference-specific markup format (based on java-
doc), a reference-specific naming model (targets), and renderers.

You can use these with a full-blown wiki as the editor and cms, or you
can use something else.  I'm open for all ideas.  The only things I'll keep
ignoring are unqualified vetos ;-)

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: regarding the current state of Python docs

John M. Gabriele


--- Fredrik Lundh <[hidden email]> wrote:

> John M. Gabriele wrote:


Sorry to take so long to get back to this thread
(not that it's really kicking anymore, but it's
still at least twitching for me. :). It's partly
because I hardly understood what Fredrik wrote,
but also b/c work got (and still is) crazy for
me this past week.

I'd really like to understand this though, and
think the python community will benefit not only
from Fredrik's work, but also from understanding
it better, so I'm posting.

> >> 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)
> >
> > So, I'm not quite sure what I'm looking at there. Have
> > you been taking the doc source (LaTeX) and converting it
> > to input suitable for moinmoin, or are you writing your own
> > wiki engine with its own markup style?
>
> I prefer to model things as a collection of components, and leave the
> overall architecture open for as long as possible.

No idea what you mean by that in this context. In
general I agree though. Could you briefly outline the
different components and what they envision them doing?

>  The links above dis-
> cusses converters,

Hm. Converting from some text markup language
to things like html. ok...

> a reference-specific markup format (based on java-
> doc),

Ah. So-called "PythonDoc".
http://effbot.org/zone/pythondoc.htm
Dunno what you mean by "reference-specific" though.

Seems like there would be some confusion between
PythonDoc and doc strings. In your code, where do
you put your docs, in the doc strings or in PythonDoc
comments?

> a reference-specific naming model (targets), and renderers.

Ok, I'm lost there. :)

> You can use these with a full-blown wiki as the editor and cms, or you
> can use something else.  I'm open for all ideas.  The only things I'll keep
> ignoring are unqualified vetos ;-)
>
> </F>
>

I see that there's also this "ReST" markup that looks
pretty readable even in plain text (with the markup
still in it).

So, is your idea to write Python docs in ReST, or
write them in PythonDoc? (Though, I'm guessing that
you'd only use PythonDoc to document your code, not
to write the Python reference manual with.)

Thanks,
---J


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig