[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

> I'd be happy to write up a PEP, but I'm curious what things people
> think it should include.  In particular, which of the following
> should it include:
>   1. The definition of a particular markup language?
>   2. Specification of the *semantics* of a markup langauge (as
>      opposed to just its syntax)
>   3. Specification of what is "appropriate" to put in a docstring?
>   4. Specification of the "intended semantic content" of various
>      "slots" like docstrings and strings immediately following
>      docstrings?
>   5. Specifications of tools for docstrings?  Possibly of tools
>      that would eventually be included in the standard library?
>   6. whatever else you can think of..

I'm tempted to answer, but time is running out, and in fact the easiest
answer is probably to write my own PEP.

> Some of these questions require further work to answer (such as 1,
> where no one can currently give a good definition of any version
> of StructuredText)..  Others will probably involve some agreement
> by the community..

I'm sure the community will love to argue...

(We do realise, don't we, that when we put a PEP on the main
python-list, all the arguments from the last 5 years are going to be
endlessly rehashed? Yes, I thought we did.)

> I think it's important to distinguish the tools that process
> docstrings from any attempt to define what should go *in*
> docstrings (or similar places), whether that means what type
> of information or what type of markup.  The PEP should address
> what goes *in* docstrings, but shouldn't necessarily have much
> to say about the tools that process the docstrings.  (Leave
> those for a standard library extension (do those get PEPs?).

Actually, my experience is that one can't do that separation until one
has started on the tool - otherwise the tool never gets written (because
of the community arguing referred to above). Been there, done that.

Also, ST is sort of difficult to think about without an implementation
to throw strings at and see how they behave.

> My favorite suggestion is to just use top-level description list items
> and top-level headings with a single level of description list items
> to store meta-data.. and to have "reserved" keys for description lists
> (in these contexts).  E.g.::
>
>    def primes(n):
>        """
>        Return a list of all the prime numbers from 1 to n, exclusive.
>
>        Parameters:
>            n -- The upper limit for the prime numbers to return.  A
>                 prime number will be returned if and only if it is
>                 less than 'n'.
>
>        Types:
>            n -- int
>
>        ReturnType -- 'list' of 'int'
>        Version -- 1.0
>        Author -- Edward Loper
>        See -- #other_primes#
>        """
>        ...
>
> Also, I think that *all* of these special marked meta-data fields must
> be optional.  (Of course, if the user wants to use a program that
> checks to make sure that ReturnType is defined for every method, they
> can.. but it's not required in general).

What he said. Twice (although he's got some of the markup wrong, but
that's my fault, not his).

> I therefore propose the following:
>    1. STdoc strings appear after __doc__ strings, as I said before.

I've disagreed with this elsewhere - we'll have to differ for the
moment.

>    2. For now, these strings are thrown away by the compiler

Hmm.

>    3. At some future date, the compiler could be modified so that, at
>       user option, it would produce ".pyd" files as well as ".pyc"
>       files.  These contain all the STdoc strings from the file, and
>       can be accessed via the interpreter somehow.  Python would *not*
>       format them, it would just copy them.  Maybe create a dictionary
>       from identifier name to string, and pickle it.

pyo files throw away docstrings already. It's this time machine thing,
you see.

> >> 6- the documentation parsing tools should be capable of
> producing output in
> >>      many formats (manpages, plain text, html, latex, for
> a start),
>
> definitely, although this may take some time to implement.  I
> would add
> "dynamic navigation of docs from within the python interpreter" to
> the list of possible "outputs."

Time machines again. HappyDoc and pydoc do lots of what is wanted, and
seem both to be expanding (in wonderfully different directions - btw,
have you *looked* at inspect.py - it's ever so neat).

> Possibly in a different file..  I find Tibb's arguments
> pretty convincing..

You see why I'm willing to differ with him on other issues? Can't but
help liking someone with that much sense (now, I just need to convince
him of all my other views...)

> So I'll try to write up a PEP when I get a chance.  It sounds like
> Tibbs might write a proposal too.  I think that Tibbs and I seem
> to have similar views on a lot of issues, so if we want diversity
> in our PEPs, maybe someone else should work on one too. :)  (Of
> course, this sort of seems like redundant work, but I guess it's
> for the best or something)

Actually, I think our PEPs will be sufficiently different in aim to both
be useful (and we *do* disagree on some things, flippancy aside). But,
as I said elsewhere, I also suspect that I will want *both* our PEPs to
be adopted.

(different aims can produce different useful things. That's why I keep
referring to HappyDoc and pydoc - superficially similar, but actually
rather different in aim and implementation)

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.)