Windows Help Format

October 13, 2008

Just ran the hhc compiler after doing Sphinx’s make htmlhelp. This results in a Windows help .chm file which is really impressive (considering how simple it was to create). A no-brainer for windows users.



October 13, 2008
  • Managed to get Sphinx working without errors. The output is quite nice, and there is even a built-in search function.


  • I’m trying to figure out how to get the Sphinx Latex output to build. It appears that Sphinx will produce everything in Latex that would be necessary to create a book (goes right to PDF, there is an indexing facility) so it would be very nice if the book never had to go to Word at all; could just be kept in Sphinx format and go right to HTML for viewing onscreen and directly to PDF for printing. That would be very impressive and useful indeed.
  • Need to create standalone code extractor (create code tree from book) and updater (incorporate code automatically into book)
  • Once I do the above two things, I think the project will be ready to post on Launchpad so people can start getting Bazaar checkouts.
  • Might need to create a basic page on how to run Bazaar.
  • I’m sure we’ll have some experimenting to do before the process of forking and reincorporating goes smoothly, so at first no one should do any big changes, until we all figure out how things work.


October 13, 2008
  • Installed sphinx, ran sphinx-quickstart
  • Modified my build program to create book so that each chapter is a subdirectory (I think this will produce a simpler architecture for people to follow, because each chapter will then be a standalone little article. Also chapters can easily be rearranged, since the Sphinx index.txt file controls the order of chapters).
  • Diagrams are now in proper subdirectories. Eventually I hope that all diagrams can be (re) created using something like Omnigraffle. Note that you can use any tool you want to create initial diagrams; only when the book is being prepared for print will the diagrams be revisited and polished if necessary (would Google Sketchup be a good suggestion for people who don’t already have a diagramming tool?).
  • I think I followed the instructions for Sphinx, but got an error message when I ran make so I joined the Sphinx newsgroup and submitted the error along with my project. Will wait and see what they say, or for a fix.


October 9, 2008
  • Converted headlines to follow Python doc standards, as suggested by Sphinx.
  • Began adding notes using the .. note:: syntax
  • Further editing and massaging of document


  • Convert diagrams from Word book and insert them into restructured text version
  • Write code insertion program (I have the code extractor to create code tree from document, but I want to also be able to automatically pull/refresh document listings from code tree)
  • Reorganize document hierarchy into Sphinx format. Before I put the document up on Launchpad, I’d like the initial architecture to be established, so people can just follow along.


  • I’d like to move the book’s feature list to Launchpad’s “Blueprint” system and start using that, but so far I haven’t found the docs for Blueprints.

Sphinx Seems Good

October 7, 2008

I’ve been going over the Sphinx docs, not in depth but just trying to get the sense of it. So far I’m impressed.

  • It’s Restructured Text with (most of?) the missing parts filled in. There are lots of additional features and tags that will be useful in creating this book.
  • The output options seem much better, and it provides templating for a custom look.
  • It’s been road-tested on the new python documentation.
  • The structure of a multi-chapter project has already been decided, so it doesn’t need to be figured out for this book.


October 6, 2008
  • Installed docutils
  • Managed to get TIPython to convert to HTML without errors by editing, and by writing
  • Figured out regular expression to split book into chapters, (purchased RegexBuddy to help)


  • Dividing book into smaller pieces, as an example of the smaller chapters I hope to have. (Note that I don’t expect all the material to necessarily survive into the final book, but it is at least useful as seed material for the project).
  • Someone suggested I look into as a document creation tool. It apparently uses restructured text so it may be a no-brainer to move to. It does appear to impose a structure on the directories used for the source of the document (a useful thing, actually, since otherwise I’ll have to invent such a structure). I’ve only glimpsed at the docs but so far I’m inclined to use it.


    October 2, 2008


    • Read through the Bazaar docs. Became more convinced that the best approach is just to use all the launchpad facilities.
    • Created this scrum blog.
    • Continued converting the “Thinking in Python” doc to restructured text.


    • Auto convert all the code listings to the new format in restructured text
    • Need to start trying docutils on the output of the above doc
    • Will use the above doc as the starting point for the book (won’t necessarily keep everything in it, but it will be good starting fodder, where we can set up and test out the tools

    Stuck on

    • Not sure what the various categories mean in wordpress, whether the project team members should just be “authors” or what.
    • Not sure whether the project should just have a single gateway committer. Probably start that way and change to pair review if that seems better.
    • Not sure about the structure of the project in terms of Bazaar. I should probably ask my friends Barry Hawkins and Mark Ramm, both of whom know a lot about version control.

    What is a Scrum Blog?

    October 2, 2008

    We’re working on this project from all over the world, in all different time zones. We can’t have stand-up meetings in the same room at the same time, but all the same, communication is good.

    So, whenever you’ve done something, write a little report on this blog, and say:

    • What you’ve done
    • What you’re planning to do
    • Where you’re stuck