[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

> Edward said:
> > Among other (very good) reasons, this would mean that only the writer(s)
> > of a module can write tutorials, discussions of usage, etc. for it..
> 
> erm ... are you suggesting this is how it should be or ...

Sorry, that was unclear.  My stance is:

    Inline documentation should include clear, concise definitions of
    what guarantees are provided by the Python object they document.
    I will call that "API documentation."  Inline documentation should
    *not* include tutorials, howtos, extended explanations, unreasonable
    amounts of background information, etc.

That way, the module author writes the "definitive definition" of the
module's behavior.  But everyone else is free to go write tutorials,
etc.

> The source code should contain documentation addressing the following
> needs:
> 
>   * the maintainer needs to know what the code does and why

s/the maintainer/anyone reading the source/
Note that what the code *actually* does and what it *promises* to
do are very different things (but hopefully the former is a superset
of the latter).  For example, code may *promise* to return 
a list of names, but the order in which it *actually* returns it
is not specified..  So the API docs let you distinguish what is
part of the design from what is an implementation choice..

>   * someone manipulating an object (or function) supplied by the code
>     needs to be able to interrogate it (e.g. at the interpreter's
>     prompt, but equally possibly in code) to find out what it is and can
>     do - and how to get it to do what it can do - without needing to
>     know where it comes from.  [I'll call this `someone' the
>     interrogator for distinction from the maintainer.]

I think this should generally be the same as what I called the
API docs..

> Neither of these forms of documentation needs anything like the
> sophistication of markup that *is* genuinely needed by tutorials,
> reference manuals, etc. 

I'm not sure reference manuals always need more markup.  For
example, the reference manual for the entire Java library 
basically uses almost no markup, and is very readable/useful.
But I can see how reference manuals can benefit from extra
markup (esp. if you want to write real math equations).

> Granted I'd sooner the `other doc' language was a richer ST, rather than
> a totally different language (much as I like TeX) from the one used in
> docstrings.  

I think this will have to be a discussion and/or project for 
another day, though. :)

-Edward