[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 
section:

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" 
directories.

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".

--rich



More information about the Twisted-Python mailing list