Using Hudson to build Sphinx documentation

   2010-03-21      Computing · Software      Hudson · Python · Sphinx

I have become quite the fan of both Hudson and Sphinx. At Cantemo we are using Hudson for Continuous Integration testing, and its a large improvement over buildbot which I was trying before.

For documentation at the moment I am using Sphinx, a python based documentation generator. We require the documentation to be updated at the same time as the development and tests are built so it is becoming second nature to build documents soon after development is done.

Sphinx allows the creation of documents in ReStructured Text and has build options for creating HTML, LaTeX, PDFs and other version of documents so I tied it into a Hudson build.

Firstly you need a working Hudson installation. There are many tutorials on doing this that work fine, so please google for one. You will probably have the following requirements for following the rest of the steps:

• Hudson Python plugin
• pip installed for python
• VirtualEnv installed for python

Second you need a Sphinx project that can be built.

1. Firstly create a new job in Hudson, call it what you want. I am using the free-style software project type.

   

2. Now start filling in the details. I am going to check out from subversion (you can also use HG, Git or whatever.). The repo URL will be checked when you fill in the details, and you will have the option to supply username and password credentials. The user Hudson is running under on my linux box has public/private key SSH authentication.

   An example of the URL is:

   [cc lang=“bash”]http://your host/yourrepo/development/Documentation/Development/trunk[/cc]

• Now create a build shell.

  [cc lang=“bash”]

  cd $WORKSPACE

  virtualenv -q docs

  source ./docs/bin/activate

  pip install -q -E ./docs -r trunk/requirements.pip

  cd trunk

  sphinx-build -b html source build

  [/cc]

  This is:

  • Change to the current workspace directory
  • Create a Python Virtual Environment called docs
  • Activate that environment
  • Use Pip to install the requirements held with the sphinx project
  • Change into the trunk directory
  • Build the HTML version of the sphinx documentation
    

  My screenshots show an extra step for Rsyncing the files to a remote host. This is because I want to publish the results of the build. The FTP and SCP plugin for Hudson are not so great so I prefer manually rsyncing as a build step for now.

My Sphinx project is checked out above the source files, and in this location is a requirements.pip file for pip to use when installing into the Virtual Environment. This file is basically:

[cc lang=“python”]

sphinx

Pygments>=0.8

[/cc]

You could also put your project in here so that sphinx can auto-document modules, or put other requirements for PDF generation.

Then try a build.

comments powered by Disqus