[Doc-SIG] suggestions for a PEP
Edward D. Loper
edloper@gradient.cis.upenn.edu
Wed, 14 Mar 2001 10:07:00 EST
> > 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!
Um. So did I. I'm not sure where you got the impression that I
didn't. Hopefully having special places to describe arguments is
useful in new code? I wasn't even thinking about the std library..
> Aagh! Quick, do a "from __future__ import docutils" 'cos that's all
> being addressed in the alpha release and *it's already coded*.
So, my main objection to this format (given that I'm the one that
has to formalize it) is that it means we're giving meaning to
yet another character: ':'. I read through the list archives, but
didn't seem to find eventual consensus. But if we're going to have
it, here's how I would *like* it to be defined:
1. *Any* paragraph starting with '\w+:' is a "label paragraph."
2. Any ':' in any other location is treated as a normal ':'
3. It is illegal for a label paragraph to contain a newline.
4. If a label paragraph has (non-space) content after the ':',
then that is parsed as the only subparagraph of the label
paragraph.
5. If a label paragraph does not have content after the ':',
then following indented paragraphs are subparagraphs.
6. If a label paragraph has content after ':' *and* is followed
by indented paragraphs, then... I'm not sure. Could be illegal.
Could all that the following paras are children of the para
that's on the same line.. Ideas?
>
> OK. The rules for "paragraph labels" (I changed the term) are fairly
> simple. Basically, there are two dictionaries::
>
> label_dict = { "Label" : "xml-label" }
If we're going to be xml-like in specifying contents, then we
might want to consider using actual xml DTD-like strings to
specify this (so "Label" : "ANY"). :)
> 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.
Agreed. Although this is bound to confuse people.. :) But
according to my rules, it will produce an error if they have
error checking turned on..
> 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.
Again, I don't like giving even more meaning to ':' when we could
just give '--' the same meaning, and say it's a "tool issue" to
decide whether a key has special meaning.. But as long as we
give ':' special meaning *only* and *always* when it appears directly
after the first word in a paragraph, I can accept it.
> More explanation can (please) wait until the alpha release, which I
> *hope* will be end of next week, with the PEP.
Looking forward to it. If my emails take too much time to answer,
just punt them for now. :) I've been trying to get some answers
out of your source code, but I don't have the time to figure out
everything that's going on in there..
> > 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?
Yes, I was thinking of "now" as "before the PEP is accpeted." :)
> > >> 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).
I didn't think this was possible, because the following fails::
B.f.__doc__ = A.f.__doc__
But really you have to do this:
B.f.im_func.__doc__ = A.f.__doc__
It might be worth mentioning this in documentation, because I think that
the whole idea is not quite intuitive, and it's something that the
code writers would have to do.. So we should suggest that they do it
when applicable! :)
> See, as I said, time machines...
Time travel's fun! :) But I'm sure you've been through all this too many
times to count. I'm a bit new to all these issues, so if I seem dense
sometimes, please forgive.. :)
-Edward