close ticket #4239 (fixed)
close ticket #4336 (fixed)
close ticket #4348 (fixed)
create “master ticket” in trac : Use Sphinx for Documentation
use script (“lore2sphinx”) to convert lore docs to sphinx format
- make sure external entities are included
- turn off lxml parsers recover from errors functionality
build new sphinx docs
- set TOC :maxdepth: to 0
- manually fix any Sphinx markup that causes build errors
create a branch: “lore2sphinx-conversion-XXXX”
move the new sphinx docs into the branch
split up the docs into reasonable-size chunks
create a “task” ticket in trac for each chunk
have people grab a ticket:
review the rst markup of their chunk for markup errors
if non-markup errors are found, open a new ticket
if markup errors are found either:
- apply changes to the branch to fix the errors, and close the ticket for that chunk
- or attach a patch to the chunk-review ticket, and mark with “review” keyword
once all docs have been reviewed for markup errors, and all “chunk-tickets” closed, merge branch and close master ticket
(at this point, all new docs should be submitted in Sphinx format)
open a ticket for: fixing up the ‘twistedtrac’ sphinx theme (the new trac site is great, but the sphinx theme will need to be updated)
open ticket for: deploy new docs to website
open ticket for: update buildslaves to build new docs
open ticket for: update documentation to reflect conversion
write new Twisted Documentation Guide
- document writing sphinx docs
- document :api: extension role
remove/replace references to Lore throughout docs
remove old Lore docs or update them to reflect that Lore is no longer actively maintained
open ticket for: anything else???
either close open Lore tickets, or mark them as lowest priority
- projects/conch
- projects/core/development
- projects/core/howto (except ‘tutorial/’)
- projects/core/howto/tutorial
- projects/historic
- projects/lore
- projects/mail
- projects/names
- projects/pair
- projects/vfs
- projects/web (everything except web-in-60)
- projects/web/web-in-60
- projects/web2
- projects/words
check out the branch
build the docs (requires sphinx ~0.6.4 or so)
- look over the docs for this chunk
look ONLY for markup errors, missing content, or other things related to conversion
be sure to look at both the .rst and .html files
grep for xhtml tags still in the document (sometimes they sneak in inside comments)
- if you find another problem, see if there’s a ticket for it
- if there is, make a note on the chunk ticket and move on
- if not, create a new ticket, and leave a note in the chunk ticket
either commit fixes back to the branch, or attach a patch to the chunk ticket