[Doc-SIG] Python docs in reST

[Michael Foord]

Hello All,

I agree with your comments about writing documentation - any moderately 
large framework *needs* properly written  documentation rather than just 
an API reference.

But :

Martin Blais wrote:

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

Even where the documentation is being separately written and maintained 
it would be *useful* to have an 'extract docstring from source' 
directive - so that the docs (where appropriate) don't need to be 
maintained twice. This is different from autogenerating the whole of the 
documentation.

Best Regards,

Fuzzyman
http://www.voidspace.org.uk/python

>[snip..]
>cheers,
>_______________________________________________
>Doc-SIG maillist  -  Doc-SIG at python.org
>http://mail.python.org/mailman/listinfo/doc-sig
>
>
>
>  
>