[Twisted-Python] web page on doc...
kevin.horn at gmail.com
Tue Feb 16 13:59:59 EST 2010
On Tue, Feb 16, 2010 at 12:17 PM, K. Richard Pixley <rich at noir.com> wrote:
> 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".
I think that an overview like this is a great idea, though in your text
the xhtml is processed into html by "lore" not "trial". With any luck this
change soon, and the long-form documentation (how-tos, etc.) will transition
to Sphinx. If you'd like to see what that looks like, see here:
Other than that, something very like what you have described should
be _somewhere_ on the Twisted site.
(As an aside, I think a lot of things that are currently on the wiki should
into the documentation proper, but that's a topic for another post.)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Twisted-Python