[Twisted-Python] Task-based documentation started

[Tom Davis]

I have the beginnings of some task-based documentation available in
twisted-docs (https://github.com/tdavis/twisted-docs) now. You can find the
built version in the usual place (http://docs.recursivedream.com/twisted/)
-- just remember to bust the cache.

I chose serving web content as a starting point because it seems as common a
task as any. I took some examples from the existing howto (
http://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html),
as well as added some examples of further learning and glossary entries to
make the point. Obviously there's nothing completely usable here yet; it's
primarily an exercise in showing how I'd like to split up sprawling,
semi-random docs like *using-twistedweb* into more coherent, digestible,
stackable pieces. A document to talk about core concepts (Site Objects,
Resources, etc.), sections for supplementary features like Sessions, Virtual
Hosts, etc.

Another advantage of this style is that we can effortlessly stitch together
our own tutorials (were that ever a goal) just by linking in step-wise
fashion to ever-advanced tutorials which themselves wrap back around to core
concepts like, in this case, Applications and the IService stack. It should
be up to the user how deep into the rabbit hole they want to go; right now I
have to slog through two sections to get to a part that tells me how to just
serve a directory of HTML.

Thoughts?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110131/74b014d0/attachment.html>