Last month I found some issues with the TurboGears 2 documentation and the guys on the TG IRC channel told me I should download the docs and do something about it. Alas, I didn’t know what I was doing, but with their guidance I got the code and it was mostly set up. Then my work got in the way and I forgot all about it. Yesterday I got into another conversation about the sad shape the docs are in on the same IRC channel and this time I decided to do it right. Here’s how you can get set up so you can help too!
If you just want to jump in, read the short directions at the end.
First, you need to have virtualenv and setuptools installed in your default python install. Virtualenv allows you to create a “virtual” environment with it’s own copy of python and a virgin set of libraries. Why would you want to do this? Because it makes experimenting with packages much easier. You can download and try anything you like without screwing up your main installation and if you find you don’t like the package, you just delete the folder that contains the virtual environment. Setuptools is needed for easy_install purposes, which is something that TurboGears utilitizes a lot.
Once you have that stuff downloaded and installed, open up a command window (or shell) and navigate to a location where you’d like to create a virtual environment. Then type the following where “exampleFolder” is the name of the folder you want to create the virtual environment in.
virtualenv --no-site-packages exampleFolder
The “–no-site-packages” flag tells virtualenv that you do not want to copy your entire tree of site-packages from your main python installation. I recommend this as I have lots of stuff in my site-packages that I don’t want in my virtualenv.
Next, you need Sphinx and you can’t just use the current 0.6.2 version as it doesn’t work right with the TG2 (as of 07/16/2009). Instead, you’ll need 0.6.2+, which you can get here. To download the source from bitbucket, you’ll need Mercurial. I recommend getting the command line version as the GUI tended to mess up file open dialogs on my Windows box due to the way Mercurial did shell overlays (it also screwed up WingWare IDE). This may be fixed now. Once you have Mercurial, follow the “hg clone” directions on the site linked above. Then change directories until your inside the source and run “python setup.py install” to install Sphinx.
The next step is to get the docs themselves. You have two choices. You can go with the ones on TG2’s main website, or you can get mpedersen’s set. Just so you know, mpedersen is the IRC handle of the guy who has volunteered to lead the effort in the documentation clean-up. The only difference is that his set will have fixes already in it along with a todo list on each page. I recommend his so that the duplication of effort will be at the minimum. You use the same “hg clone” command there as you did for the hacked Sphinx source in the last step.
The next to last step is to download the TG2-dev source and install it. Here’s the Mercurial command to get the source:
hg clone http://bitbucket.org/mramm/tg-21/
Now just install it like you did with Sphinx above. Note that the dev code depends on SqlAlchemy and doesn’t install it automagically, so be sure to easy_install that as well.
We’re almost there now. The last step is to build the docs. To do this, navigate into the “docs” sub-folder of the docs you downloaded and run the following command (or if you’re on Linux, use “make html”):
sphinx-build -b html -d _build/doctrees . _build/html
Now you can browse the html versions of the docs! Remember, to edit the docs, you must edit the rst files, not the html ones. When you’re ready to contribute them back, you’ll use the “hg push” command. I haven’t done this part, so hit up mpedersen on the turbogears IRC channel for more info.
To recap, here’s a short list of what you need to do:
1) Create a clean virtualenv and activate it
2) Download Sphinx 0.6.2+ from https://bitbucket.org/birkenfeld/sphinx-06/
3) Get the docs from the main website or from mpedersen
4) The dev source depends on SqlAlchemy, so easy_install that
5) Get the TG2-dev source and install it
6) Go into the downloaded TG2 docs sub-folder and run
“sphinx-build -b html -d _build/doctrees . _build/html”
(without the quotes)
7) And you’re done!