A long time ago I spent a Christmas trying to figure out the best way to solve the problem of documenting my plugins for Rock RMS. I’d decided I wanted each to have a standalone website and that I wanted them all to look and feel similar by using a common template. The documentation would live alongside the code by using Github Pages but I was still struggling with one problem - how do I update all of my plugins if the template changes? I solved the problem, but unfortunately and somewhat ironically I didn’t document it at the time. So a year and a half later I’m revisiting the process to iron out and wrinkles and document the process.

The Big Picture

The big picture is this, each individual documentation website (served from Github Pages) consists only of the minimum number of files required, the rest uses a master Jekyll template which is pulled during the Travis CI build step. Any change to the master template is captured by a webhook running on Google App Engine which then triggers a Travis CI build of all documentation sites.

The Template

The template (and consequently the sites) are Jekyll based and use a mixture of JQuery, FontAwesome, raw CSS, Bootstrap, and other outdated web technologies. The template is loosely based off of Bootstrap 3’s documentation. All in all it’s pretty raw but does the job relatively well.

The template stores a copy of the build scripts, the Gem file, and boilerplate _config.yml.

Travis CI

Travis CI combines the repo specific documentation files with the template.

Config

Jekyll is configured via _config.yml , stored in the template, which includes the boilerplate variables used in every documentation site and also placeholders for the plugin name and repo name which are replaced during the build step.

Travis specific configuration is stored in the .travis.yml file found in the root of the plugin repository. It specifies the branches that builds can be triggered from (just pages-ci), the variables for the name of the plugin and the name of the repo, and an encrypted Travis variable for the GitHub Token (GH_TOKEN=...) used to push deploy to GitHub. For convenience, you can fetch this from travisencrypt.arranfrance.com.

Build

Most of the build process is stored in the scripts found in the template but the Travis file has the commands to fetch the main install script from the template repo via curl, make the necessary files executable, and run deploy.sh.

The main scripts of interest are ciinstall.sh which clones the template, then copies the template on top of the Travis build folder, fetches the necessary Ruby gems, and runs replace.py to overwrite placeholder values in the Jekyll config file.

There are a couple of idiosyncrasies in order to serve the site both locally and on GitHub with minimal fuss. deploy.sh uses sed to replace {{site.github.url}} with {{site.baseurl}}. If this isn’t done URLs all fail to point to the correct place either locally or when served via GitHub in production. I’m sure this is a terrible way of doing it but it works for the moment. There’s an outstanding issue to investigate it further.

Before deploying html-proofer is run on the site to ensure there are no dead links. There’s definitely room here to do some further testing (spell-checking as well as JS and CSS testing).

Plugin Site

Each plugin site has a page-ci branch where all the documentation specific files live, these are then built with the template, and pushed to the gh-pages branch - effectively deploying it. The plugin specific files are purely any additional assets required (typically images), documentation/index.html, index.html, and .travis.yml.

Webhook

Ultron is a Python 2.7 webhook run on Google App Engine. It receives notifications when any repo from the BricksandMortar organisation is pushed to, a branch or tag is created or deleted, or a repo is created or deleted. It tracks repositories with pages-ci branches in a Google Cloud datastore. Whenever a push occurs to the template repo it triggers Travis CI builds on all of its tracked repositories. It is set up with Travis CI to auto-deploy to Google Compute on every push to the master branch.

Ultron is configured with config.py which contains the secrets for GitHub and Travis, a bricks-build-docs-...json which contains the Google Cloud configuration, and an app.yaml which contains the Google App Engine configuration. As both config.py and bricks-build-docs-...json contain secrets they are stored in the repo as secrets.tar.enc and are unencrypted during the build step.