One of the many nice touches of the Django framework is that it provides tools and instructions to make a standalone Django documentation set from its distribution.  (Django is an application framework for the Python language that helps with database access and web application.)  Standalone docs are great for people like me who work on a laptop and are sometimes off the net. But I’m using Mac OS X, I get my code through Macports, and Django’s instructions don’t quite cover this case.  So I just figured it out.  Here’s the tricks I needed.  Maybe it will help you.

I installed Python 2.6 and Django for Python 2.6 via Macports.

sudo port selfupdate
sudo port install python26
sudo port install py26-django

Django includes its documentation in source form.  It tells you how make the documents as HTML, locally (i.e. standalone). Their instructions didn’t quite work for me.  Here’s some adjustments to their instructions for my situation.

First, you need to install the Sphinx document generator utility. This is part of the Python project code-base.  It’s installed via the Python easy_install utility. You need to specify the 2.6 version of easy_install though:

sudo easy_install-2.6 Sphinx

(MacPorts also has a version of Sphinx, named  py26-sphinx. I tried this, and it failed, conflicting with the Sphinx installation from easy_install.  I’m guessing you need to use one method or the other, not both.)

Now, Django’s instructions tell you to “cd path/to/django/docs“. Which directory is that, exactly?  Macports puts Django under /opt/local/Library/Frameworks  (I’m adding line breaks to the path, since this blog format doesn’t handle long lines well):

/opt/local/Library/Frameworks/Python.framework/Versions/
    Current/lib/python2.6/site-packages/django

But there’s no “docs” directory there. Macports moves the Django “docs” directory to “/opt/local/share/doc/“, so use this path:

cd /opt/local/share/doc/py26-django/docs

Next, Django’s instructions tell you to execute the command “make html”. This failed for me for two reasons.  The Makefile invokes a utility “sphinx-build”, and this utility wasn’t on the path. I discovered that my shell’s path was pointing to the Mac OS X copy of Python in /Library/Frameworks/…/bin. Since I am using a Macports-supplied release of Python, that is the release to include on the path, i.e. in /opt/local/Library/Frameworks/…/bin. My Python-related PATH modification now reads (line break added):

set path=(/opt/local/Library/Frameworks/Python.framework/Versions/
    Current/bin $path)

Another way to fix this problem was to specify the path to sphinx-build as an environment variable, and then tell make to let environment variables override the Makefile’s own variables (line break added):

setenv SPHINXBUILD /opt/local/Library/Frameworks/Python.framework/Versions/
    2.6/bin/sphinx-buildmake -e html

The second failure (for me) was that Sphinx threw a NameError (line break added):

Exception occurred:  File "/opt/local/lib/python2.5/socket.py", line 75, in <module>_realssl = ssl
NameError: name 'ssl' is not defined

It looked like Sphinx was picking up the Python 2.5 version of socket.py.  Why would this be? Python-select appeared to have version 2.6 selected, as it should have. Nevertheless, deactivating the Macports copy of python25 worked around Sphinx’s choice of socket.py. (A side effect of using easy-install instead of macports to install Sphinx? Or of having the wrong Python bin directory on my path?)

% python_select -s python26% sudo port deactivate python25--->  Deactivating python25
make -e html

Next came a directory permissions error. (Line breaks added.)

Exception occurred:  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.6/
    lib/python2.6/site-packages/Sphinx-0.6.2-py2.6.egg/sphinx/environment.py",
    line 654, in read_doc
f = open(doctree_filename, 'wb')
IOError: [Errno 13] Permission denied: '/opt/local/share/doc/py26-django/
    docs/_build/doctrees/contents.doctree'

Ah! The _build directory and its descendants were owned by user ‘root’, with group ‘admin’. Directory permissions were drwxr-xr-x. The workaround was to make _build writable by the group:

sudo chmod g+w _build/ _build/*make -e html

This finally allowed Sphinx to build the documentation, and put it into _build/html. Thus I could load the standalone Django documentation from my browser by loading this URL:

file:///opt/local/share/doc/py26-django/docs/_build/html/index.html

There, that was simple, wasn’t it?

I’m tagging this post as “robobait” in the hopes it will help others figure this out.  Enjoy Django!

2 Comments »