[Doc-SIG] PEP-0216

[Tony J Ibbs (Tibs)]

First, status of my weekend work:

I had less time than I hoped, due in part to our youngest not being very
well, so all I've done at the moment is work out more-or-less what is going
on in STNG as it stands. I've got a document that describes what I've learnt
so far - although I don't guarantee much beyond its existence, it's at
http://www.tibsnjoan.demon.co.uk/STNG-format.html in case anyone wants to
criticise.

Next thing to do is to actually produce something a little more formal, and
easier to read!

Second, worries about documentation as a whole...

((NOTE that this is what I would regard as pedantry - we are going to use
STNG for docstrings, possibly subclassed, and everything else is frills. So
continue at your peril...))

I was worried that Moshe wanted to do ALL the documentation using STNG (or
whatever tool we decided on), but assumed that I was probably actually
mistaken.

Moshe Zadka wrote:
> If you read the PEP carefully, you'd notice that I'm thinking of
> docstrings in two related ways: parse time and run time. The parse time
> docstring is a superset of the runtime docstring. The runtime docstring
> is the memo, the parse time is the book.

Oh dear, I was right. (I would point out I find the terms "parse time" and
"run time" to be most misleading - there's documentation derived from the
docstrings (be it at run time in an IDE, or on paper/the web statically),
and there's documentatation written as such. OK, in the literate programming
world there's an attempt to unify these, but we're not in that world. If
Moshe is just assuming that *all* documentation for a module will be in
docstrings, then I'm very confused.)

I continued:
> > I think I'm also upset if you expect people writing manuals to
> > have to use the same format designed for docstrings, since the
> > AIMS are different - docstrings must be pleasant to read "as is",
> > by people inside the code, or people using a class browser, but
> > very few people (um, well) read HTML or XML or TeX raw, and most
> > people don't even *write* them "raw".
> > And in "real" documentation you often want to have closer control
> > over what is going on than StructuredText will allow.

To which Moshe replied:
> I don't believe that is true: as you say, nobody wants to write HTML or
> XML or TeX.

Firstly, some of us (ME!) do like writing using HTML, XML, TeX or whatever.
What I *said* was that I had learnt that *most* people don't, and that if
one wants documentation in docstrings, you cannot expect them to use
"heavyweight" documentation methods, or you don't get the documentation. So
STNG is perfect for docstrings.

There is also an argument to say that, if one wants (external) documentation
for a module, then a neutral format usable by everyone can also be useful -
at the moment that tends to be either a README file in ASCII text, or an
HTML page. For these, STNG can also be a win, as has (presumably) been
proven by the Zope world.

(But note that I do NOT regard these two as interchangable, nor do I *want*
them to be.)

Moshe wrote:
> Not really: I'm not saying documentation for a module *must be* in the
> module, I'm saying the format must be flexible enough for it to be
> able to. What people will do is their own business.

which is OK so far as it goes. He continued:

> In my last proposal after IPC8, there was an elabortate
> template/docstring/xml trinity. At the time it was dismissed by Fred
> as irrelevant: it seems there are less then 5 people on the face of the
> planet interested in documentation outside the modules, so he can
> decide on the format himself. I told him I *am* interested, and if
> you are, you should tell him so too. In any case, the relationship
> between a manual outside and a docstring inside is yet to be defined,
> and not by PEP-0216.

Hmm. Fred is producing the Python documentation set, to a professional
standard. He is using professional quality tools for this purpose. STNG is
*not* adequate for this job. It cannot be so without getting *way* too
complicated, because producing a BOOK (which is what the Python
documentation set is composed of, even if the books are also viewable as web
pages) is a different and more complicated thing. I believe he is right when
he says very few people are interested in doing this, and I also trust him
to get it right (he's done a wonderful job so far).

This **is** a different issue than what we are discussing for STNG. It
*should* be handled by a different mechanism. Full stop. Not a point to be
argued about. Ask Fred.

As to docstrings and per-module documentation, some of us (me, me!) will
feel constrained by the simple formatting that STNG allows, but will put up
with it in docstrings because it does a good job at what it does, and one
has to have a standard. The question of documentation *outside* the module
is still open, so far as I'm concerned, and STNG is just one tool that will
get used for that (I'm not saying there *should* be more than one tool, I'm
saying that in practice there *will* be more than one tool, although I
expect that if STNG is easy enough to use it will be the most prevalent,
which would be a Good Thing on the whole.).

> Let me just note that as a Perl hacker, the fact that the documentation
> (up to and including the tutorial and manual) being *inside* the code
> is very convinient. E.g., knowing that "perldoc HTML::Mason" just
> works, and gives me everything I need. Indeed POD is a large part
> of my inspiration.

What does "inside the code" mean in this context? If it means "inside my
single .py file", then no, it's a Bad Thing, because it makes my .py file
too long, and also makes it hard to distribute the documentation WITHOUT the
code (or to amend one without changing the other!). If it means "inside the
directory of my module" then it's not so bad, but on installation I damn
well want the documentation putting in the Appropriate Place (so I can find
it!) - on systems without such a standard place, then inside the module
directory is still good, of course.

And note that a decent piece of documentation is itself often
file-structured (i.e., made up of more than one thing that one would
normally keep in a separate file).

I *think* we're probably still talking at cross purposes, and could resolve
matters a bit better with some concrete examples - lets promise to do that
at a later date.

But luckily, regardless, the initial stage of getting STNG based python
documentation in docstrings off the ground is still something we all want...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)