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 _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
