[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
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
>
>
>
>
>
More information about the Doc-SIG
mailing list