On Mon, 2007-07-02 at 08:46 -0700, Martin Poirier wrote:
--- Carsten Haese carsten@uniqsys.com wrote:
However Id be interested to know how other
On Mon, 2007-07-02 at 23:30 +1000, Campbell Barton wrote: projects deal with the issue
of maintaining docstrings and online docs.
I maintain separate docstrings and online docs for one simple reason: The online docs can be more extensive than docstrings. Docstrings are for brief memory-joggers. Online documentation can contain examples and generally more detail that's not appropriate for docstrings.
Can you elaborate on this a bit. What kind of tools do you use to generate/maintain your docs?
My needs are probably significantly different, i.e. smaller, than yours. My documentation is all in one moderately sized Restructured Text file. If you were expecting automatically generated hyperlinked API docs, you'll be disappointed.
I was merely making the point that in my opinion it's not a problem to have two sets of documentation because docstrings and online documentation serve different purposes. Your opinion may vary.
-- Carsten Haese http://informixdb.sourceforge.net