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 - [email protected] >http://mail.python.org/mailman/listinfo/doc-sig > > > > > _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
