[Twisted-Python] web page on doc...
K. Richard Pixley
rich at noir.com
Tue Feb 16 13:17:31 EST 2010
I've been going around and around on documentation with/for twisted for
a few days now. For example, I read things like "the documentation is
written in epytext" and "documentation is processed by trial" and
conclude that trial processes epytext. I think I'm beginning to
understand what's really going on now but two things would have helped me.
1) a brief overview of the documentation. (proposal below).
2) if references to "the documentation" could be clarified to refer to
"howto documentation" vs "API documentation".
If agreed, then I will volunteer to help find and patch #2. As a
proposal for #1, I offer the following as an insertion into
http://twistedmatrix.com/trac/wiki/ReviewingDocumentation as a second
UNDERSTANDING DOCUMENTATION ORGANIZATION
Documentation for Twisted comes in four primary parts.
The first part is a collection of "Howto" documents which are composed
in xhtml, processed by twisted's "trial", into html. The source for the
Howto documents lives in subversion under doc in the various "howto"
The second part is a collection of examples. These examples are
included inline in the "howto" doc. These are written in python and
twisted and are included in the various "examples" directories under
"doc" in the source.
The third part is the API documentation which is produced by pydoctor
from the docstrings scattered throughout the twisted source code. The
doc strings are written in epytext format.
The fourth part are traditional unix man pages. These are written in
troff -ms format and the sources are stored in the various "man"
directories in the source under "doc".
More information about the Twisted-Python