[Doc-SIG] Python docs in reST

Michael Foord mike at pcblokes.com
Wed May 18 13:20:12 CEST 2005

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 

Best Regards,


>Doc-SIG maillist  -  Doc-SIG at python.org

More information about the Doc-SIG mailing list