<div class="gmail_quote">On Tue, Feb 16, 2010 at 12:17 PM, K. Richard Pixley <span dir="ltr">&lt;<a href="mailto:rich@noir.com">rich@noir.com</a>&gt;</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&#39;ve been going around and around on documentation with/for twisted for<br>
a few days now. For example, I read things like &quot;the documentation is<br>
written in epytext&quot; and &quot;documentation is processed by trial&quot; and<br>
conclude that trial processes epytext.  I think I&#39;m beginning to<br>
understand what&#39;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 &quot;the documentation&quot; could be clarified to refer to<br>
&quot;howto documentation&quot; vs &quot;API documentation&quot;.<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 &quot;Howto&quot; documents which are composed<br>
in xhtml, processed by twisted&#39;s &quot;trial&quot;, into html.  The source for the<br>
Howto documents lives in subversion under doc in the various &quot;howto&quot;<br>
directories.<br>
<br>
The second part is a collection of examples.  These examples are<br>
included inline in the &quot;howto&quot; doc.  These are written in python and<br>
twisted and are included in the various &quot;examples&quot; directories under<br>
&quot;doc&quot; 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 &quot;man&quot;<br>
directories in the source under &quot;doc&quot;.<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 &quot;lore&quot; not &quot;trial&quot;.  With any luck this will <br>change soon, and the long-form documentation (how-tos, etc.) will transition<br>
to Sphinx.  If you&#39;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&#39;s a topic for another post.)<br><br>Kevin Horn <br>