This chapter describes all the processes related to the documentation of the POP-Java project.
The POP-Java project currently has two main types of documentation:
- Prose documentation
- The documentation you are reading right now. It contains manuals, guides and how-tos about the project itself. The prose documentation is written by humans for humans. This documentation is currently edited using Sphinx.
- API reference
- The API Reference contains the documentation for each functional unit of the project (packages, classes, methods, …) and is generated by parsing the source code. The API reference is currently being generated using Doxygen.
Editing the prose documentation¶
As mentioned in the previous section, the prose documentation is managed by Sphinx. Sphinx is a tool to create documentation from reStructuredText sources and can produce a variety of output formats (e.g. HTML, LaTeX -> PDF, ePub, Texinfo, man pages, plain text, …).
The prose documentation resides in the
docs/ directory at the root of the
repository and can be edited with any text editor. The complete reference for
the reStructuredText syntax and the addons added by Sphinx are available on
the reStructuredText (see also
Sphinx Markup Constructs pages,
For quick and small edits, it is possible to use the GitHub editing interface instead of a complete local clone + edit + commit + push process. The documentation files are available on GitHub in the gridgroup/pop-java repository.
Building and publishing the prose documentation¶
The building process transforms the input documents in reStructuredText format into one of the output formats supported by Sphinx (HTML, PDF, ePub, …).
There are two different ways to build the documentation:
- Locally on the development machine, by installing the necessary tools and executing the right command.
- Remotely, via a custom post-commit hook on a CI server or through a specialized service, such as http://readthedocs.org/.
In the next two subsections we will discuss these two possibilities. In the second case we will limit ourselves to building through http://readthedocs.org/.
To build the documentation locally we need a working Sphinx installation.
Sphinx requires at least Python 2.5 or 3.1; you can read more about additional details regarding the requirements on the Sphinx introduction page.
To check which version of python you have installed, run the following command:
If python is not installed or does not meet Sphinx’s version requirements,
you can either install or update it by using your distribution package
apt-get on Debian/Ubuntu,
yum on CentOS/Fedora,
Below we report some easy steps to install Sphinx on your system. For a more complete walk-through (including platforms such as OS X and Windows), you can always refer to the Sphinx installation instructions.
To install Sphinx, you can use either
pip install sphinx
Depending on the platform and your setup, you probably have to run these commands with administration privileges:
sudo pip install sphinx
You can check if Sphinx was successfully installed by running the following command:
python -c 'import sphinx'
In addition to Sphinx itself, this documentation makes use of one additional required and one additional optional packages:
bibtexextension allows to use BibTeX databases to manage references. You can install it by executing:
pip install sphinxcontrib-bibtex
sphinx_rtd_themeis the theme used on Read The Docs. If the corresponding package is installed, it will be used for local builds as well. The theme can be installed by running:
pip install sphinx_rtd_theme
If you had to use
sudo When installing Sphinx, then the commands to
install these additional packages will have to be prefixed with it as well.
Once you have a working Sphinx installation on your system, it’s time to start building your documentation. As the initial setup is already done for the POP-Java project, you don’t have to configure anything.
Different ways exist to build the documentation. The easiest is by far to use
Makefile present in the
cd path/to/pop-java/docs/ make html
If successfull, the last line of the command output will indicate the location
of the build. In this case, the HTML files will be located in
To publish the generated documentation, it suffices to upload the
directory (or the equivalent artifact for a different output format) to a
publicly accessible web server.
In order to support the other output formats managed by Sphinx, the
Makefile has different additional targets. You can find out more about them
by running the
help target, whose output is shown below:
Please use `make <target>' where <target> is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and a HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX files and run them through pdflatex latexpdfja to make LaTeX files and run them through platex/dvipdfmx text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items xml to make Docutils-native XML files pseudoxml to make pseudoxml-XML files for display purposes linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled)
Read the Docs (RTD) is a free service to build and host Sphinx documentation sets. It supports polling any GIT or Mercurial repository and re-running a build each time a new commit is detected. The POP-Java documentation is currently available on RTD at the following link: http://pop-java.readthedocs.org/en/latest/.
In order to update the documentation hosted on RTD, it suffices to commit the changes to the GIT repository and push them to the GitHub remote:
git commit -m 'Documentation update' git push origin master
The repository hosted on GitHub is configured with a post-commit hook to trigger a new RTD build and the updated version should be available in a short time (usually < 2 minutes).
Thanks to RTD’s integration with GitHub, an even easier way to carry out small, self-contained edits to the documentation is directly through the GitHub editing interface:
Each HTML page generated on RTD contains a GitHub edit link in the right corner which brings up the GitHub interface browsing.
We can then click on the edit button to enter the editing interface.
From there we can carry out the desired changes, commit them directly (if the account with which we are logged in to GitHub allows it; fork and open a pull request otherwise) and have the documentation hosted on RTD updated automatically.
Building and publishing the API reference¶
In the introduction to the present chapter we mentioned that the API Reference is currently being generated using Doxygen. In the following paragraphs we will describe how the documentation can be rebuilt and how the resulting artifact can be published on the GitHub pages service.
To build the documentation you need a working installation of Doxygen on your system. Extensive documentation about the installation process is available directly from the Doxygen manual.
Once installed, the steps needed to build the documentation are very simple:
The resulting build will be available in the
doxygen/latex directories. The HTML version is ready to use, while the
LaTeX version needs and additional build to get to the PDF version:
cd doxygen/latex make
The resulting PDF will be available at
Publishing on GitHub pages¶
GitHub supports a basic kind of static website hosting, based on GIT repositories. This service is called GitHub pages; you can find out more about it on http://pages.github.com/.
Currently, the latest build of the HTML version of the API reference is made available for browsing at http://gridgroup.github.io/pop-java/api/ and the PDF version at http://gridgroup.github.io/pop-java/api/POP-Java.pdf.
The steps involved in the update process of the
gh-pages branch (the branch
from which the static website is made available on GitHub) are summarized as
git checkout gh-pages # Checkout the 'gh-pages' branch mv doxygen/html api # Move the built HTML reference into place git commit -am 'API reference update' # Commit everything git push origin gh-pages # Push to GitHub (publish) git checkout <oldbranch> # Go back to the branch we were working on
To make it easier to build and publish the documentation, a script to automate
the process is made available at
scripts/api-reference from the root of the
repository. In order to build, commit, and publish a new version of the API
reference, it suffices to execute it with no arguments: