On 4/23/05, David Goodger <[EMAIL PROTECTED]> 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, _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
