1st November, 2011
Recently, EllisLab greatly improved their documentation, and at the same time moved to using Sphinx to manage it. Sphinx is a documentation generator originally used for Python, and which is now used for many open source projects.
The beauty of using Sphinx is that you can write your documentation using ReStructuredText, a text format similar to MarkDown. You can then easily generate your docs in a variety of output formats, including HTML and PDF. It also helps to keep your content separate from design, and automatically handles repetitive tasks such as generating a table of contents / navigation, and linking between your documents.
For some time, we had been thinking about how we could improve how we handle our documentation. Initially, we tried simply writing HTML from scratch. This has the advantage that it can be easily included with our add-on. However, it becomes a pain if you need to alter the layout and linking (for example to include on our live website). Eventually, we settled on storing our documentation in ExpressionEngine on our live site. This means it is easy to alter the layout and design of our docs. However, there are two main downsides - we cannot include a static HTML version with our add-on, and it prevents us from documenting features as we implement them (we must wait until we have released a version before we can update the docs on our website).
When EllisLab announced that they were moving to using Sphinx to manage their documentation, we decided to take the plunge, and attempt to move our docs to the same system. Overall, the experience has been pretty good, and we would certainly recommend other ExpressionEngine add-ons and CodeIgniter projects move to this system. The following is a simple tutorial for getting started if you wish to move your documentation to Sphinx.
To use Sphinx, you must have Python installed. If you are using Linux or Mac OSX, you should already have Python. Python has its own package manager, called easy_install. Therefore, the first step is to get easy_install up and running on your system. For more information, see http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install.
Once you have easy_install, we need to install Sphinx. From the command prompt, run the following commands:
$ sudo easy_install sphinx
$ sudo easy_install sphinxcontrib-phpdomain
The next thing we need to do is create a new Sphinx project. Following the CodeIgniter convention, a good name for this directory would be `user_guide_src`. We always set our add-ons out using the following layout:
/add_on_name
/system
/expressionengine
/third_party
/add_on_name
/themes
/third_party
/add_on_name
This helps keep everything consistent, and also makes perfectly clear to the customer where they should be uploading the various folders to. Therefore, we would like to create a user_guide_src directory in the root of our add-on directory. To do this, run the following commands in your terminal:
$ cd path/to/add_on
$ mkdir user_guide_src
$ cd user_guide_src
$ sphinx-quickstart
The sphinx-quickstart wizard will ask you a bunch of questions. You can accept the default for nearly all questions. The only ones you need to pay attention to are:
> Project name:
> Author name(s):
> Project version: 1.0
Many of the questions relate to built-in documentation code testing, which we will not be using. After the wizard has completed, you will have the following new directories:
/user_guide_src
/_build (documentation output appears here)
/_static (this is where you can add any static content, such as css and images)
/_templates (you can override the theme templates here if necessary)
/conf.py (documenatation output settings)
/index.rst (the index page of your documentation)
/Makefile (used for building your documentation)
To build your new documentation, simply type
$ make html
in your terminal. The documentation will be converted to HTML format, and placed in `_build/html`.
By default, your html output will use the default Sphinx theme. We want our users to have a consistent experience with their ExpressionEngine and CodeIgniter documentation. Therefore, it would be best to use the same or similar theme to the one EllisLab use for their official documentation. Luckily, a Sphinx theme named “eldocs” has been included in the CodeIgniter repository on GitHub. Unfortunately, the theme is very specific to EllisLab’s needs, and contains lots of hard-coded references to their sites. To work around this, we have created a fork of the eldocs theme, and are naming it “cidoc”. This is available on GitHub, and licensed under the same Open Source License v3.0 as CodeIgniter. Our primary goal with this theme is to create a consistent look and feel which anyone can use to document their ExpressionEngine and CodeIgniter projects, while also remaining flexible so that the theme can be easily customized.
To use the Cidoc theme in your project, the easiest method is to add it as a Git “sub-repository”. This means that you can easily update to the latest version of the theme, independently of commits to your master repository. To add the Cidoc theme, run the following commands in your terminal, from the root of your project:
$ mkdir user_guide_src/_themes
$ git submodule add git@github.com:adrianmacneil/cidoc.git user_guide_src/_themes/cidoc
If you ever want to upgrade to the latest version of Cidoc, simply cd to the cidoc directory, and run `git pull`. If you aren’t using Git to manage your project, start now. Git provides huge benefits to older systems such as Subversion, even for single-developer teams. It is also rapidly gaining popularity over other distributed systems such as Mercurial and Bazaar, and it’s worth knowing how to use tools which you will more than likely need in future employment. If you really don’t want to use a subrepo though, you can simply download the Cidoc theme from GitHub, and unzip it into your project directory.
The final step is to modify your `conf.py` file to specify the theme you want to use. The lines you must modify are:
html_theme_path = ['_themes']
html_theme = 'cidoc'
You can then run `make html` from the terminal again, and your documentation will be generated in the beautiful CodeIgniter style. We want to continually improve the Cidoc theme, both to increase usability (on all devices), and to make it as flexible and customizable as possible. Therefore, if you have suggestions, feel free to fork the project and send a pull request via GitHub.
To find out more about using Sphinx, and documenting your ExpressionEngine and CodeIgniter projects, the following resources may be helpful:
To see the results of our move to Sphinx, check out the new Expresso Store Documentation.