[Twisted-Python] web page on doc...

[Kevin Horn]

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
> 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
>
>
I think that an overview like this is a great idea, though in your text
above,
the xhtml is processed into html by "lore" not "trial".  With any luck this
will
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:
http://twistedsphinx.funsize.net

Other than that, something very like what you have described should
definitely
be _somewhere_ on the Twisted site.

(As an aside, I think a lot of things that are currently on the wiki should
be merged
into the documentation proper, but that's a topic for another post.)

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100216/743f57ab/attachment.htm