[Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code

[Martin Blais]

On 4/23/05, David Goodger <goodger at python.org> wrote:
> [Martin Blais]
> > 2. unifying source code and readable documentation
>
> This is a debate that's been going on for a long time.  I'm not going
> to get into it again :-)

well, i didn't mean necessarily that we should convert fred's docs
back into the source code, but that there should be a way for people
to be able to do that in their own libraries.  but certainly we should
make something that is good enough to be able to do that with the
python sources themselves...


>
> > we might want to do something to couple the source code and the
> > written manual, e.g. where we could have a template that outlines
> > the "manual" versoin of the documentation, and our directive would
> > go fetch the docstring for the function or class and insert it
> > inline in our document automatically.
>
> You're talking about "literate programming":
> http://www.literateprogramming.com/

yes and no.  there exists some codes should not appear in the
documentation (answer: pull model with templating system).  there
exists some documentations that should not appear in the code, more
generic manuals (answer: separate file, pull model for selected code
bits).  i'm trying to find a middle ground.

cheerrs, thx for the links,