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

[John M. Gabriele]

--- Fredrik Lundh <fredrik at pythonware.com> 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