We've all done it. One step forward, two steps back. I just thought I'd try to relieve my current frustrations by writing this particular sequence up. It's amazing the diversions and byroads you can end up taking to achieve an apparently simple goal (as I learned yet again last week in trying to accommodate Outlook on my SMTP server). This one started at PyCon, now four weeks in the past. So, bear in mind the goal: submit a Django documentation change.
At the Django sprint (of which, due to a family illness, I was only able to attend a truncated first day) I was struggling with an unstable laptop, so I managed to assign myself a documentation ticket, and that turned out to be pretty much it what with PSF responsibilities and needing to go home early. I have been working on the ticket since: it isn't a difficult issue, but I needed to learn a little more about how the Django database layers worked.
Having finally decided on the required change, during entry in the Django tracker I decided it would be much more developer-friendly if I were to provide the change in the form of a patch. This isn't really necessary but I figured it couldn't hurt, and that I should really be able to rebuild the documentation locally to be sure that any future changes were stylistically correct and didn't mangle what is, after all, quite good documentation.
This is where things started to get a little rough. Descending into the documentation directory I discover that it's driven by a Makefile. "No problem", I think, "I have Cygwin, I can build under that". So I type "make html" and discover I don't have make installed. This is quite normal, I like to keep Cygwin fairly lean, and I haven't previously done any Cygwin building on the new laptop.
So, I run the usually very cooperative Cygwin installation utility, and discover that my usual mirror site is providing very slow response. So slow, in fact [minor pause here to repair cable retraction mechanism on traveling mouse: this really is not my day] that several attempts to update my installation have to be abandoned, though it notes that several of my other installed applications should also be upgraded and has even managed to pull down some of the installers.
Eventually the fifth or sixth attempt gives me the dread message from Vista (how I hate this operating system, yet despite my best efforts there are tasks I currently still need it for) that the Cygwin installer "is not working correctly".
After a reboot and several further repeats, I eventually track this down to a corrupted /etc/setup/openshh.lst.gz file, and delete it. I establish contact with a different mirror and lo! The Cygwin installer now runs to completion, and I can run make. So I confidently re-enter "make html" and see the message
make: sphinx-build: Command not found
Fair enough, it shouldn't (I foolishly think, despite all the evidence that should by now have convinced me to set the computer aside for the day) take me long to get that up. As a first stab, before doing anything else, I type "easy_install sphinx-build". Hello, another even more interesting error message:
bash: /c/Python25/Scripts/easy_install: Permission denied
What? ls -l gives me the following rather unsavory news:
----------+ 1 sholden None 6656 Apr 2 10:33 /c/Python25/Scripts/easy_install
Damn, that can't be right? How did that happen? Well by this time I am past caring how it happened. I own the file, so I'll just reassert the correct permission, right? Wrong:
$ chmod 755 /c/Python25/Scripts/easy_install chmod: changing permissions of `/c/Python25/Scripts/easy_install': Permission denied
Now this is getting really annoying. Note how my problem has subtly changed from "how do I submit a Django documentation change" to "how do I get Cygwin to allow me to change the permissions on this file", and that I am now several steps further away from my original goal than I appeared to be at that happy moment when I set out to submit the change. Note also the assumption that running easy_install is actually necessary to solve my problem. If this had turned out to be wrong I would probably have shot myself, thereby relieving you of the task of reading this post.
Fortunately I quickly realize that this is the easy_setup from my Windows Python that I am trying to run, and that the solution is to run ez_setup.py with my Cygwin Python. [There are some who doubt the wisdom of doing this to a Python installation, but I am blasé beyond belief about such things]. So I run ez_setup.py, which installs setuptools. There is the minor annoyance that Cygwin refuses to recognize the correct version of easy_install and continues to run the Windows copy, but I solve that by opening a new Cygwin terminal window. Another final false start: the package required isn't called sphinx-build, so easy_setup can't load it. So I take another reasonable guess.
Now, finally, I run easy_install sphinx followed by make html, and in less time than it take to write a blog entry I have a local copy of the documentation that I can patch to my heart's content. Wonderful things, computers. When they do what you want.