Archive for October, 2008

Bruce

October 28, 2008
  • Partway through the series of articles on Decorators that will become the Decorators chapter.
  • Still trying to understand and configure the initial structure; I’m trying to get most of the questions answered before the initial post so we can move forward and spend less time on such decisions.
  • I’m going to try to put the artwork for the cover into the Sphinx docs (it has a way to do that). Not the cover itself yet, but the artwork.
  • Figuring other things out about the Sphinx sidebar.
  • The initial posting will be rough anyway, I know, but I’m trying to sort things out well enough that it will be reasonably self-explanatory.

Bruce

October 18, 2008

 

  • Wrote and posted Decorators I: Introduction to Python Decorators, which is a starting point for a chapter on decorators.
  • Modified document so that all the Java code in the Jython chapter is pygmentized (colorized).
  • Corrected capitalization on headers so it’s consistent.

Bruce

October 18, 2008
  • Jython chapter is mostly integrated. It turns out there is pygments code highlighting support for Java built into Sphinx, which I’m now including.
  • Spent some time studying decorators, which are much deeper than they seem. I am planning a couple of weblog entries which will become part of a new chapter on decorators.

Next:

  • Fix footnotes from Word version to Sphinx format. Some other cleanup necessary, but it’s very close
  • Figure out how to set up to begin working through Launchpad.net.

One More Delay

October 13, 2008

I was reminded about the Jython chapter from “Thinking in Patterns” (where it doesn’t get much notice, as far as I can tell). It belongs in this book, so I’m in the process of moving it before the initial release. Since it includes Java code this will require a bit of extra reworking. But I think it will be a valuable chapter in the book, once it’s brought up to the latest version of Jython.

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.

Bruce

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

Next:

  • 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.

Bruce

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.

Bruce

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

Next:

  • 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.

Challenges:

  • 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.

Bruce

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

Next:

  • 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 http://sphinx.pocoo.org/ 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.