[Python-Dev] [Doc-SIG] that library reference, again

[Fredrik Lundh]

Donovan Baarda wrote:

> > No, it's a fundamental goal: to support light-weight generation of rendered
> > markup directly from source code, to enable simple tools (CGI scripts, etc)
> > to be able to render reference documentation.
>
> Python is run-time interpreted, but I don't think we need its
> documentation to be.

Are you sure ?

>>> help(help)

>From the pythondoc/lib goal list:

    Support tighter (and 2-way) integration between the library reference
    and help tools (pydoc, help, inspect, etc) and documentation generators
    (epydoc, pythondoc, etc).

> "trivial" is a relative term.

When I say "trivial" in this context, I mean that any programmer should
be capable of writing a Python tool that does some kind of basic processing
of the source format from scratch.  The easier it is to do this, the more
likely it is that someone will come up with a new way to use the information
("Web 2.0", you know...)

> As a some-times developer not really interested in writing
> documentation, I must admit I really like ReST. It looks like plain
> text, so I can write and use it as plain text, but it also can magically
> transform to other formats and look pretty good.

Lots of "looks like plain text if you squint" formats can produce output
that looks pretty good.

The problem is semantics; I haven't seen any format that looks like plain
text but provides the amount of machine-readable semantic information
that we have today.  And I want more semantics, not less.

> I hate writing XML/HTML, and my only experience with LaTex was brief and
> painful too. If I was forced to choose, I'd probably pick LaTex even
> though I don't know it as well as XML/HTML (I'd rather face an unknown
> evil than that particular devil I know).

Familiarity breeds contempt ?  We're not talking about well-formed XML
here, nor 1996-era hand-rolled web sites.  If you look at typical Java-
Doc or PythonDoc markup, or the translated samples, you'll notice that
the source code contains very few HTML tags.

(I seriously doubt that your problems with XML/HTML is the use of < in-
stead of {...)

> I'm not going to write docs for stuff I didn't write myself. I'm not
> going to submit patches to Javadoc, LaTex or XML/HTML, but I might post
> vague "change this to..." bug reports.

> Writing good documentation is hard (which is why I prefer to leave it to
> others if I can), but fixing almost good documentation doesn't have to
> be /.../

Since I'm focussed on the library reference, I'm a lot more interested in
the fixers than the essay writers.  Give people a way to find things to fix,
and a way to fix it, and they will.

> > It's the workflow that's the real problem here, but you cannot fix the workflow
> > without fixing the markup.
>
> I must say I disagree with this statement... changing the markup will
> not change the workflow at all, just shave 3-6 mins off the compile-test
> step. I don't do this enough to really know if that's worth it.

Do you think wikipedia would be what it is today if the edit/save process
included a 3-6 minute "regenerate site" pass ?

Heck, I've discovered dozens of bogosities in the current library reference
while working on the translation tools, and I have the sources and full SVN
access, but I find that the overhead discourages me from doing anything
about them ("maybe later").  I simply don't have time to fix anything but
very minor typos within a standard 15-minute "let's improve python" time
slot, and I sure don't think I'm unique in this respect.

</F>