[capi-sig] Documenting a C/Py API

[Carsten Haese]

On Mon, 2007-07-02 at 08:46 -0700, Martin Poirier wrote:
> --- Carsten Haese <carsten at uniqsys.com> wrote:
> 
> > On Mon, 2007-07-02 at 23:30 +1000, Campbell Barton
> > wrote:
> > > However Id be interested to know how other
> > 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