<div class="gmail_quote">On Tue, Feb 16, 2010 at 12:17 PM, K. Richard Pixley <span dir="ltr"><<a href="mailto:rich@noir.com">rich@noir.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
I've been going around and around on documentation with/for twisted for<br>
a few days now. For example, I read things like "the documentation is<br>
written in epytext" and "documentation is processed by trial" and<br>
conclude that trial processes epytext. I think I'm beginning to<br>
understand what's really going on now but two things would have helped me.<br>
<br>
1) a brief overview of the documentation. (proposal below).<br>
2) if references to "the documentation" could be clarified to refer to<br>
"howto documentation" vs "API documentation".<br>
<br>
If agreed, then I will volunteer to help find and patch #2. As a<br>
proposal for #1, I offer the following as an insertion into<br>
<a href="http://twistedmatrix.com/trac/wiki/ReviewingDocumentation" target="_blank">http://twistedmatrix.com/trac/wiki/ReviewingDocumentation</a> as a second<br>
section:<br>
<br>
UNDERSTANDING DOCUMENTATION ORGANIZATION<br>
<br>
Documentation for Twisted comes in four primary parts.<br>
<br>
The first part is a collection of "Howto" documents which are composed<br>
in xhtml, processed by twisted's "trial", into html. The source for the<br>
Howto documents lives in subversion under doc in the various "howto"<br>
directories.<br>
<br>
The second part is a collection of examples. These examples are<br>
included inline in the "howto" doc. These are written in python and<br>
twisted and are included in the various "examples" directories under<br>
"doc" in the source.<br>
<br>
The third part is the API documentation which is produced by pydoctor<br>
from the docstrings scattered throughout the twisted source code. The<br>
doc strings are written in epytext format.<br>
<br>
The fourth part are traditional unix man pages. These are written in<br>
troff -ms format and the sources are stored in the various "man"<br>
directories in the source under "doc".<br>
<br>
--rich<br>
<br></blockquote></div><br>I think that an overview like this is a great idea, though in your text above,<br>the xhtml is processed into html by "lore" not "trial". With any luck this will <br>change soon, and the long-form documentation (how-tos, etc.) will transition<br>
to Sphinx. If you'd like to see what that looks like, see here:<br><a href="http://twistedsphinx.funsize.net">http://twistedsphinx.funsize.net</a><br><br>Other than that, something very like what you have described should definitely<br>
be _somewhere_ on the Twisted site.<br><br>(As an aside, I think a lot of things that are currently on the wiki should be merged <br>into the documentation proper, but that's a topic for another post.)<br><br>Kevin Horn <br>