[Doc-SIG] Python docs in reST

[Martin Blais]

hmm...  I have come to the following conclusion: there are two types
of documentation, and they are completely separate beasts, and I feel
that we should start recognizing this difference.

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.

Most of the recent discussions I hear about documentation blur this
distinction, and I believe that this is making the discussions a
little bit unfocused.  Fred's approach with Python was to build (2),
which is why IMHO that Python docs are so great.  We need to recognize
that writing documentation is a task in itself, and no amount of
intelligent processing over docstrings will ever produce user manuals
that are fun to read.

My beef with this approach is that the docstrings are not used, and
the documentation of functions has to be maintained by hand, in the
doc file which is completely separate and far away.  I have been
proposing a way to share those bits and pieces (the docstrings) so
that one could write a user manual independently, but still document
the low-level functions in the docstrings and have that information
pulled into the manual selectively.

I feel that (1) is often not very useful.  My experience working on
large C++ codebases where the auto-documentation tools were working
well and used consistently is that most people still used the source
code rather than the generated HTML pages (and certainly this is what
I did too).  With emacs everything is available C-s or a tag away, or
a grep away (or with LXR if you have that).  I'd actually prefer to
read from the source because other cues gave subtle information about
the intent of the programmers (or lack of intent).  However, many
people want to generate that kind of documentation.  We just have to
make sure what our intention is.  Oftentimes I feel that it is our
programmer's instinct that makes us believe we can automatically
generate (1), while really, it's not really possible.

So anyway, it would be great if we could clarify the context of our
intent in the discussions about documentation, whether we want to
build (1), or (2), or to state clearly if we want to generate both
from a single source, or whatever.  Just an idea.

cheers,