Documentation on steroids with Sphinx, GitHub, Travis-CI and Platform.sh!

Documentation website for the new Akeneo REST API

Documentation is often the first entry point to your product, this is why you should care about it.

A well-written documentation adds value to your product and increases your reputation. It reduces the need of support and makes people enjoy their journey with your product.

Even if investment on documentation quality is worth it, it’s difficult and time consuming. At Akeneo, we’ve been using a new process since weeks to simplify the maintenance and make contributions to the documentation easier.

Investing on standards

How do we write our documentation

In the documentation world there are two established languages to write and describe documentation: reStructuredText and Markdown.

At first sight RST and Markdown look alike: both are markup languages that emphasize plain-text readability.

While Markdown is intended to be used as a format for the Web, reStructuredText is more extensible, adds semantic, and is intended to write technical documentation.

This is why we chose Markdown for the API documentation and reStructuralText for the technical one.

How do we generate documentation for the web

The most widely used tool to generate a documentation from reStructuredText is Sphinx. Sphinx is written in Python and thus is available in every platform (Windows, Mac OSX and GNU/Linux).

Sphinx quickstart helps you generate the configuration file

Thesphinx-quickstart command generates the configuration file conf.py and the structure of the documentation.

Once the configuration is all set, you can build the HTML documentation by running sphinx-build -b <format> <sourceDir> <builddir> .

And this is it! You can now open build/index.html in a web browser and discover what Sphinx has built from your RST files located into thesource directory.

Some of you may have noticed there is a Makefile so you can also execute make html to produce the same result.

Sphinx can generate documentation in many formats such as LateX or PDF. You can refer to the “builders” documentation for the full list of supported formats.

There are two other features that make Sphinx able to generate very unique documentations:

• Sphinx supports themes and provides a templating engine
• Sphinx can be easily extended using Python language

Those very popular open source projects are using Sphinx!

Make validation easy and automatic

The biggest problem with generated content is: how one can be sure that the content is valid and won’t break the layout?

The biggest problem with generated content is: how one can be sure that the content is valid and won’t break the layout?

This is why we have to validate both the reStructuredText format and its rendering.

Validating reStructuredText the right way

We can thank one more time the Sphinx contributors for providing a built-in validator to sphinx-build.

Arguments can be:

• -n Runs in nit-picky mode. Currently, this generates warnings for all missing references.
• -W Turns warnings into errors. This means that the build will stop at the first warning and sphinx-build will end with an exit status.
• -T Displays the full stack trace if an unhandled exception occurs. Otherwise, only a summary is displayed and the stack trace information is saved into a file for further analysis.
• -b dummy This builder produces no output. The input is parsed and checked for consistency.

Protip: use the dummy builder if you only need to lint your documentation!

And because the command can exit with a status code, why not using a continuous integration service like Travis-CI or Jenkins?

This is how your Travis configuration file could look like:

Travis build from Akeneo PIM documentation

On the fly generation with Platform.sh

We have validated the reStructuredText files so the generation of the website won’t fail in production. But what if we had updated the website theme and assets? What if we had introduced a buggy javascript plugin?

The best validation would be to build the website from the contribution and allowing every reviewer to access it. This is how contributions on the Symfony documentation are getting approved.

I have good news for you: it’s not that hard to implement and make your contribution workflow easier :)

List of checks on the Akeneo PIM documentation project

In the next article, I’ll detail how to set Platform.sh up and connect it to your GitHub repository so you have a fully “on the fly” documentation link on all your pull requests!