[Doc-SIG] suggestions for a PEP

[Edward Welbourne]

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

well, anyway, I definitely think someone other than the module author
*should* be able to supply the tutorial, and preferably *without* having
to edit the module's *source*.  I am not as good at *explaining* things
as I am at *designing* and *implementing* them; and when I'm
*maintaining* some code I really don't want the tutorial getting in my
way.

Granted having the tutorial in a separate file from the source does
imply (so I'm now at odds with my earlier message - Tony's messages
since have been reminding me of things I've forgotten since last time
doc-sig visited these topics) a danger of getting out of sync ... but
having a huge tutorial doc in the file just means I^H the maintainer
gets into the habit of paging through large swathes of documentation
without looking at them, hence maintains the tutorial only as much as if
it *had* been in a different file, while risking missing things which
*look like* tutorial (etc.) docs but are actually pertinent to the
implementation.

The source code should contain documentation addressing the following
needs:

  * the maintainer needs to know what the code does and why

  * 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 am tempted to be wilfully contentious and add: and nothing else; but,
in any case, these two are the priorities for doc strings (particularly
the latter - hints to the maintainer can go in comments).  All other
docs belong some place else, to which the module docstring should refer
via the xref mechanisms ST* provide.

Neither of these forms of documentation needs anything like the
sophistication of markup that *is* genuinely needed by tutorials,
reference manuals, etc. and maintaining in-code docs *will not happen*
if it has more sophistication to its markup than the bare minimum that
suffices to deliver the above goals.  So the docs in other files must be
in a richer markup language than the docstrings can afford to call for;
yet another reason to put them in a separate file.

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.  But let the module *source* be as small as is compatible
with the needs of maintainer and interrogator.

Sometimes a very powerful tool, requiring minimal explanation for the
maintainer and not much for the interrogator, needs screeds and screeds
of tutorial, reference, etc. documentation - typically to lead the user
into only using it in the ways that are actually safe (powerful tools
being somewhat prone to needing such care).

> Possibly in a different file..  I find Tibb's arguments pretty convincing..
Tibs is like that.  Get used to it and *use* him ;^>

>> - documenting Packages
> There definitely need to be provisions for that.
erm ... we already have __init__.py, so a __doc__.py might be cool ?
Possibly alongside __doc__.stng or some such containing the ref docs ?

>> - documenting extensions in other languages
> Much easier if we can import modules.  But I guess safety's important.
> Oh well.

erm ... if someone's idea of having .pyd files goes through, mayhap
extension.so could come with extension.pyd providing the matching docs,
as if it had been compiled out of a notional extension.py

Importing modules is entitled to have side-effects such as changing the
way other modules work; and these changes are apt to be designed on the
premis that the module is being imported for the sake of *using* it, not
introspection.  So at least *some* of the doc-tools must be prepared to
do their own parsing; albeit the interrogator's perspective takes for
granted that the module *is* imported.

	Eddy.
--
I believe in getting into hot water; it keeps you clean.
                                    -- G. K. Chesterton.