On Tue, Feb 16, 2010 at 12:17 PM, K. Richard Pixley <r...@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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
