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