[Twisted-Python] Refactoring Documentation

[Kevin Horn]

I alluded in my earlier mail to some of the improvement ideas I have had
regarding Twisted's docs (other than the conversion to Sphinx), and I though
I'd elaborate

Here's some things I had "planned" (yes, I'm using the term loosely) to try
and add/improve/fix in the Twisted docs after the Sphinx conversion was
finished:
(urg, I know I've been keeping a list of these someplace, and some are in
trac tickets, etc. but I can't find it right now, so I may ramble a bit)

-  Add a basic intro to Twisted.  This would introduce some basic ideas
similar to the krondoblog tutorial, but in less detail.
- "What is Twisted good for"
- Explain the most important parts of Twisted for people to get started
with.  IMO, this is a) the reactor, b) deferreds, c) some of the basic
interfaces/classes, esp. Factories/Protocols
  (I'd like to see some docs on Transports as well)
- more/better UDP stuff
- "How to test your Twisted apps" (e.g., the idea of faking up a transport
never occurred to me until I read a test that did it, and it's been one of
the most useful techniques I've found)
- Task-based docs - how to serve a web page, how to send a mail, how to
write an IRC client (just to cut down on the questions!) etc. The basic
stuff at first (what newbie's will be looking for), maybe eventually turning
into a "cookbook" of sorts.
- A revamped section on "How to write twisted documentation", since that
would likely be very different after the Sphinx conversion ( What Sphinx
markup to use, and I also have some custom extensions, etc. which need to be
documented).
- "How to _build_ the documentation"
- Beginner's tutorial
- better glossary
- move a bunch of stuff out of the Trac wiki, and into the Sphinx project.
There's stuff there that has become de-facto documentation, which really
needs to be version-controlled, etc.
- install docs


So after looking over Tom's "skeleton" Sphinx project and a night's sleep, I
think we're pretty close to on the same page (or at least pages in the same
book).  It looks like a lot of this would be covered in Tom's Task-based
docs and the Base Documentation section ("Suiting Up", "Diving in").

So here's what I'm kind of thinking as far as combining efforts:
1) I'll continue with the "Project Documentation" conversion, while Tom
works on the other bits.  Should be fairly easy to combine them, I'm
thinking.
2) Let's leave the "Project Documentation" pretty much as-is for the moment,
until the Sphinx convo is done.
3) I wonder if at least some of the "task-based docs" shouldn't be put into
the project sections, and then just linked to from the task-based section?

Thoughts, Tom?

[As an aside, is there any way to get the Combinator stuff from the old Trac
wiki back online, or at least readable someplace? (Hrmmm, it looks like
Google's cache has it for the moment).  Also, it would be much easier to get
new contributors, especially for Windows, if Combinator worked out of the
box on Windows.  There's (or were) 3 or 4 patches in the Divmod SVN repo
that needed to be applied in order to get it to work, and now that the
Divmod site is offline it's really hard to set it up on a new machine, even
for me, and I have a working example to go from.  Yeah it's off topic, sue
me.]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110120/1569f356/attachment.htm