[Doc-SIG] Python docs in reST

[Martin Blais]

> >>If I am writing a small (ish) module I can fulfill 1 and 2 with a decent
> >>module docstring and proper docstrings for functions and classes etc. In
> >>which case I *need* to be able to auto extract the docs and create a
> >>reference doc from them.
> >>
> >>I *do not* want private methods visible in this documentation - and I do
> >>want a way of specifying that a function/method should not be included.
> >>
> >>If the 'user' is a programmer, I don't think there is necessarily a
> >>clear distinction between 1 and 2.
> >>
> >>
> >
> >well, i would argue that what you want to do is (1),
> >
> Yes :-)
> 
> > but you want it
> >in the source file.
> >
> >
> Yes, and be able to generate an API doc from it.
> 
> >i was suggesting earlier that this could be implemented by adding a
> >special docstring of your choice (e.g. __manual__) to your source
> >code, it could even be at the end if you want it to.  whatever tool
> >you use to generate documentation would first extract that flie before
> >processing.
> >
> >
> >
> >
> Why not just use the module docstring ?

can you imagine scrolling past an entire manual everytime you open a new file?
(i'm assuming we're writing real user documentation in that docstring,
not just an overview)