Installing local documentation

The Dojo API documentation available through is really handy for Dojo developers, but sometimes it can be handy to have this available offline, for development when you don’t have internet access or when it’s a bit cranky and slow. The instructions on are a good starting point, but there are a few subtleties, so I’ve adapted them by documenting the precise steps I took on Ubuntu 10.04 to get the documentation installed locally in a useful way. If you’re using a different OS, you can probably adapt them fairly easily for your purposes.

Firstly, I’m assuming you already have the Dojo and Dijit libraries installed using the standard packages. If not, install them:

sudo apt-get install libjs-dojo-core libjs-dojo-dijit libjs-dojo-dojox

You’ll also need the claro dijit theme, which doesn’t come by default with these packages. The easiest way to get hold of it is to do download the Dojo SDK, unzip it in a temporary location, and copy the dijit/themes/claro/ directory to /usr/share/javascript/dijit/themes/. Make sure it has the same permissions as the rest of the toolkit:

sudo chmod a+rX -R /usr/share/javascript/dijit/themes/claro/

Next, you need some kind of local webserver with PHP support. I chose lighttpd, as its resource demands are pretty low, even on the netbook I’ve been using. You’ll also need the XSL and Curl PHP modules, as well as Subversion. Install all of them like this:

sudo apt-get install lighttpd php5-cgi php5-curl php5-xsl subversion

You will need to enable the fastcgi module for PHP to work:

sudo lighty-enable-mod fastcgi

Also, I chose to put the Dojo documentation in a user directory on the local web server (e.g. /~user/ – substitute your user name), so I enabled the userdir module:

sudo lighty-enable-mod userdir

You need to change the PHP file upload size limit, as you’ll need to upload a rather large file later. Edit /etc/php5/cgi/php.ini and find the line starting with upload_max_filesize. Change it to:

upload_max_filesize = 15M

Also, edit /etc/lighttpd/lighttpd.conf and find the aliases for localhost. Add another for the Javascript libraries, so it looks like this:

alias.url += (
 "/doc/" => "/usr/share/doc/",
 "/images/" => "/usr/share/images/",
 "/javascript" => "/usr/share/javascript/"

Make sure to restart the lighttpd server after these changes:

sudo service lighttpd force-reload

Check the server is working correctly by creating a file called phptest.php in ~user/public_html (create the public_html directory in your home directory if you don’t already have one), with the following contents:

<?php phpinfo(); ?>

Make sure you set world-readable permissions:

chmod a+rX -R ~user/public_html/

Navigate to http://localhost/~user/phptest.php in your browser and make sure you can see the standard PHP test output screen. You can delete the test page once you’re happy.

Next, you’ll want to get hold of the API project using the following command:

svn export ~/public_html/dojo-api

This will extract the current Dojo API viewer code. Once it’s done, go into the dojo-api directory and locate the config.php file. Change the $basePath line to reflect where the API documentation will be on your server:

$basePath = "/~user/dojo-api/";

You need to make some changes to index.php to ensure it loads Dojo offline. Search for the URL where dojo.xd.js is loaded, and change it to a local URL, so it looks like this:

<script type="text/javascript" src="http://localhost/javascript/dojo/dojo.js"></script>

You also need to change css/jsdoc.css to alter the CSS URLs it loads to local ones. Make them of the form:

@import "http://localhost/javascript/dojo/resources/dojo.css";
@import "http://localhost/javascript/dijit/themes/claro/claro.css";

Once you’ve completed all these changes, make sure the dojo-api directory is world-writable (the documentation upload process that comes next needs to create some files and directories – making this more secure is left as an exercise for the reader):

chmod a+rwX -R ~/public_html/dojo-api

Now you need to get hold of an api.xml file, which contains the documentation information. You can generate one, but I find it easiest to simply download one. For example, here’s the link to the Dojo 1.5 one. Now navigate to http://localhost/~user/dojo-api/lib/upload.php. Click ‘Choose File’ and locate the XML file you just downloaded. Enter the API version number (1.5 in my case, although this is just a string identifier). Click “Run the transforms”. The page will normally say that it’s finished saving the file, but this isn’t always true. To double-check, take a look at your webserver’s error log – in my case, /var/log/lighttpd/error.log. I found an error that looked like this:

(mod_fastcgi.c.2711) FastCGI-stderr: PHP Warning:  DOMDocument::load(): Input is not proper UTF-8, indicate encoding !
Bytes: 0x80 0x99 0x73 0x20 in /home/user/public_html/dojo-api/data/api.xml, line: 111178 in /home/user/public_html/dojo-api/lib/upload.php on line 24

I investigated and found that my version of api.xml (the current, at the time of writing) was slightly faulty – I had to edit it and remove some broken encoded characters on that line – 111178. Once I’d done that, I retried the upload and it worked fine.

If you wish, at this point, you can delete the old version directories of 1.3 and 1.4 in ~/public_html/dojo-api/data.

Now, navigate to http://localhost/dojo-api/ and you should find your local Dojo API documentation. You’re done. Enjoy!