I discovered that Bitbucket provides an RSS feed which is perfectly adequate for noting changes — it just publishes the associated checkin comments. So no more need for this extra step in the process.

I just got back from a 10-day trip to CA, partly for the Adobe Max conference but mostly for the QCon conference. Not much actual work on the book done except worked with my cover designer and got the front cover done. You can see it on the book’s main page.

The artwork is a watercolor that I did a number of years ago, which I’ve always liked and (I think) strongly suggests “patterns.”

This program extracts code listings and puts them in appropriate places in the code tree off the root directory of the download. If you edit a code file, the program will also take your edits and incorporate them into the .rst file where they came from. I’ve tried to put numerous checks in to make sure that the program doesn’t accidently stomp on anything.

If you say python CodeManager.py help (or anything it doesn’t understand), it tells you its options:

Command line options:

update:

        Refresh external code files into .rst files.

extract:

Pull the code listings from the .rst files and write each listing into its own file. Will not overwrite if code files and .rst files disagree unless you say “extract -force”.

check:

Ensure that external code files exist and check which external files have changed from what’s in the .rst files. Generate files in the _deltas subdirectory showing what has changed.

display:

        Print all the code listings in the .rst files.

I think I’ve done some interesting things with the design of this program so I”m planning to blog about it; it will go into the “Comprehensions” chapter because it uses a lot of them, but it also has a couple of interesting design patterns.

Based on Yarko’s suggestion, experimented with BitBucket and the Mercurial DVCS and immediately ended up moving the project there. Hard to put my finger on why, but everything seems significantly smoother and easier. The BitBucket site also responds much faster. It has wikis for people who prefer to start by just writing code and text for contributions, if figuring out everything else is too big a hurdle at first.

We’ll need to redo the Developer Guide chapter for this new system, but the ease of working with the new system is worth it.

The project home page has the links to the new system.

• I seem to have the very basics of using Bazaar and Launchpad down. I have a shell alias called “push” which pushes up my current version to the trunk, and I have successfully done this several times.
• I’ve also figured out how to upload the downloadable packages, which you can get by pressing the “downloads” button on the Launchpad.net home page for the project.

Next:

• Figure out how to merge someone else’s edits with the main trunk. Yarko is working on putting up some relatively simple edits, and once he does I’ll experiment with those to figure out how to do it.
• I have the CodeManager.py program mostly designed and working, and I think it will go into the “Comprehensions” chapter because it’s a good example of using those, as well as some design patterns. I still need to test and finalize the “update” command, which actually takes code and puts it back into the document (and is thus a bit riskier so I want to be sure it’s working). One thing I’m doing is trying to use difflib to check to see whether a file has actually changed before updating it into the document, although I’ve always found difflib to be rather arcane and this has slowed me down.

So I’ve figured out how to use Bazaar enough to push the first version of the book onto the Launchpad site. You can get the current version here. Note that it is quite crude; there’s lots of code examples in the book that don’t work (haven’t been properly translated from their Java versions, usually).

However, you should be able to say “make html” or “build html” (although you’ll need make on your system, which if you’re on windows means the simplest solution is to install cygwin (you need to tell it to add ‘make’, and ‘chere’ is also very useful).

Give it a try, just to see if there are other issues I haven’t figured out.

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

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

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

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.