Using Hudson to build Sphinx documentationComputing · Software Hudson · Python · Sphinx
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.
Firstly create a new job in Hudson, call it what you want. I am using the free-style software project type.
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]
virtualenv -q docs
pip install -q -E ./docs -r trunk/requirements.pip
sphinx-build -b html source build
- 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:
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.