[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
(well, actually some of it is me)
> >> a. I don't actually believe that you are going to get most Python
> >> programmers to DO semi-formal markup for you. I *do*
> believe there's a
> >> good chance we'll get many people to write at least a little human
> >> readable text. So guess what I'm after...
>
> I think that a bunch of programmers would be willing to do global
> markup (special places to describe arguments, etc).  I don't think
> they would do formal coloring markup..

No, no - I meant in *new* code, rather than in old. I want documentation
in new code as well! (as for the standard library - we have precedent
for farming out bits of the code to be worked on by volunteers in the
original addition of docstrings. I bet much of it will be pretty close
to OK anyway).

> I agree with the idea, but I strongly think that things like author
> should be description list items.  Advantages:
>   * it requires no changes to current STpy
>   * it's more compatible with other STs
>   * it seems conceptually "cleaner"
>   * we don't need to give special meaning to yet another
>     character (":")
>   * it's *much* easier to describe a general mechanism, so
>     other people can extend it for their own tools.
>   * if they do something wrong, (e.g., put unordered list items
>     below "Arguments:"), then we can just format it like normal
>     ST. (and give a warning, if we're nice)
>
> Problems will come up with your formalism with lines like:
>
>   Author: Mr. bob frank    # does the . mean it's a got a sentence?
>   Things to do: eat, sleep # how does this get treated?
>
> Unless you can come up with a compelling reason for using::
>
>   Author: Guido
>
> instead of::
>
>   Author -- Guido
>
> I think we should go with the latter.

Aagh! Quick, do a "from __future__ import docutils" 'cos that's all
being addressed in the alpha release and *it's already coded*.

OK. The rules for "paragraph labels" (I changed the term) are fairly
simple. Basically, there are two dictionaries::

	label_dict = { "Label" : "xml-label" }

and::

	label_validate = { "Label" : ["para","dlist"] }

The first says that we will recognise text like::

	Label: this is a single line labelled paragraph

and::

	Label:

	   This is the labelled paragraph

and::

	Label:
	   Key -- the first labelled item

The second dictionary says that all of those examples are legitimate
(when validation is switched on). I decided *not* to complicate matters
by allowing::

	Label:
	    Only indentation makes this look like a paragraph.

because there are already enough rules about when paragraphs start.

This fits in reasonably well with David Ascher's original ideas
(thrashed out at the end of 1999), and to my eye the use of a colon is
more natural than overloading descriptive lists.

More explanation can (please) wait until the alpha release, which I
*hope* will be end of next week, with the PEP.


> >>  And although it says there that
> >> it should be left for second phase implementation, the
> start of support
> >> is already in docutils.
>
> I think it will be helpful to people if we can get this streight now.

Yes, but can now be next week, 'cos then I won't have to explain things
*quite* so many times, please?

> >> dosctrings inherit like any other value, surely?
> Um.. yes, but that's not always what you want.  Basically, if
> I define::
>
>   class A:
>      def f(x):
>         "this if f(x)"
>         return 1
>
>   class B(A):
>      def f(x):
>         return 2
>
> Then I might want B.f to inherit its docs from A.f.  This would be
> especially nice for things like UserList, so my classes will have
> docs for its methods without me having to duplicate explanations.

Then assign them. __docs__ is a perfectly valid "slot" to assign to (and
is the precursor to the whole idea of function values - see the relevant
PEP).

See, as I said, time machines...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)