[Doc-SIG] Python docs in reST

[Torsten Bronger]

Hallöchen!

Martin Blais <martin.blais at gmail.com> writes:

> [...]
>
> 1. reference docs: its structure mirrors the structure of the
> code, and it is often or best automatically generated from the
> source code and comments in the source code.  It does not matter
> very much if the private methods are visible in this
> documentation;
>
> 2. user documentation: a manual written with the specific purpose
> of educating a person about how to use the specific module.  its
> structure does not mirror that of the source code at all.  It does
> not describe all the source code, just what is needed.  There are
> code examples.  There might be different manuals for different
> types of users written from different angles.

I agree almost fully.  Maybe I just didn't get you totally correct,
nevertheless, I'd like to comment on it.

I've never been involved in large software projects, but I consider
(1) as mere source code documentation, rather than real reference
(not a useful reference, at least).

I think "TeX -- The Program" and "The TeXbook" reflect very well how
(1) and (2) should be in my opinion: Good documentation of the
source code itself (needn't be 'literate') for people who wish to
contribute/bugfix/maintain, and a real human-generated user
documentation.  The latter must be complete (it may contain a
tutorial, though).

Granted, you have to maintain both, but there is no silver bullet,
and I've found it the lesser evil so far.  If you try to force the
user to have to look at a reference generated from the source, it's
either quite awkward documentation, or you end up having two files
in one, effectively.

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus