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<br><br>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:<br>
(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)<br><br>- Add a basic intro to Twisted. This would introduce some basic ideas similar to the krondoblog tutorial, but in less detail.<br>
- "What is Twisted good for"<br>- 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<br>
(I'd like to see some docs on Transports as well)<br>- more/better UDP stuff<br>- "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)<br>
- 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.<br>
- 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).<br>
- "How to _build_ the documentation"<br>- Beginner's tutorial<br>- better glossary<br>- 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.<br>
- install docs<br><br><br>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").<br>
<br>So here's what I'm kind of thinking as far as combining efforts:<br>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.<br>
2) Let's leave the "Project Documentation" pretty much as-is for the moment, until the Sphinx convo is done.<br>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?<br>
<br>Thoughts, Tom?<br><br>[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.]<br>