New docs website
Author(s): Pupil Dev Team
March 27, 2017
All Pupil documentation - user docs, developer docs, and more - are now at docs.pupil-labs.com.
Github wiki --> docs.pupil-labs.com
Why did we decide to transition away from a Github wiki to our own static docs website?
Github wikis are stored as git repos. This is great, because you can track changes, make branches, tag versions, and do whatever else you want to do with git's powers. But, the wiki git repo is immediately visible to users/contributors from the Github web interface. This means that you can not make issues, make PRs, publish releases, visualize forks, etc.
In short, we felt ourselves outgrowing the constraints of the Github powered wikis and wanted to be able to have a docs site that could satisfy the following desires:
Markdown - Continue writing content in markdown.
Versioning - Host multiple versions and branches of docs. Version tags should be synchronized with Pupil version tags. The
masterbranch should always be the most current development branch.
Content vs Logic - Separate the docs content from the website generation logic and styling. Changes in style or website generation should be separate from docs.
Style - Have full control of styles, be able to embed videos, call APIs, etc.
Single page - Everything in one place; all docs on a single page. At first this may seem overwhelming, but enables one to easiliy
cmd + Fto find anything.
Github - Leverage the full power of Github's existing tools to visualize and track changes, make issues, assign tasks, show forks, etc.
Anyone can edit content. Just make a fork of the pupil-docs repo, edit, and make a PR.
Pupil Docs Website
To generate the website we are using
Hugo - static site generator written in
Go. Hugo is fast and has a lot of nice built-in functions.
docuapi theme and our content repo that holds all markdown files are both submodules of pupil-docs-website. The structure looks like this:
Hugo supports multiple languages of content by adding a language suffix for each file. Typical usage of this feature would look like this:
introduction.en.md for English language content and
introduction.de.md for that same content in German. Names of languages and their order or "weight" are defined in Hugo's
config.toml file. In the above example, Hugo would create a subdirectory for each non-default language such that
example.com/ could be the English language website and
example.com/de/ would host the German language website.
We (ab)use the multi-language feature so that we can build docs tags and branches. The most recent/current branch is always
master. Here's an example:
docs.pupil-labs.com/ - the most recent "stable" tag e.g.
docs.pupil-labs.com/master - the master branch - always the most recent changes to docs
To support this workflow we have written a script runs before we build the static site -
tag.sh. This script gets the most recent X number of tags and specified branches, renames files with their tag or branch name (e.g.
introduction.v093.md), and updates the hugo
config.toml file with the appropriate language settings.
We use travis-ci to build and deploy the website with each change.
We wrote a custom hook so that every time a commit is made to the
pupil-docs repository it will trigger a build for
We are happy with this transition, but also realize that it is a big shift for the community. There is still a lot to do, and we need help from the community to help us continue to improve docs.
You can help by forking
pupil-docs, making pull requests, making issues on either pupil-docs, pupil-docs-website, or docuapi.