Hosting Sphinx Documentation on GitHub
As many other Python-based projects, we use Sphinx to document the various components of Transifex.
Recently, we wanted to decommission the server that hosted the documentation of our service since the rest of Transifex has already moved to a different cloud provider. We already preserve the history of the docs in Github, so, instead of moving the docs section to the new provider, we took a chance on Github pages and it soon became obvious that it’s really worth it.
For those that are unaware, Github allows for any project to host static HTML content by default. You simply have to create a new branch named gh-pages, and put all the content there.
It would be wonderful if we could combine that handy Github feature and Sphinx, wouldn’t it? Let’s skip the “guess what” cliché and move forward to show you how to do it yourselves.
This is how our docs repository looks like:
. +-.git | ... +-gitignore +-docs +-theme | ... +-plaintext +-Makefile +-index.txt ...
We cloned the same repository a second time into a second directory named gh-pages, and checked out the gh-pages branch.
Now the directory structure looks like this:
. +-gh-pages | +-.git +-master +-.git | ... +-gitignore +-docs +-theme | ... +-plaintext +-Makefile +-index.txt ...
By editing master/docs/plaintext/Makefile, we set OUTDIR to ../../../gh-pages. That way, every time someone issues make html, it will populate the gh-pages directory with the correct html pages.
The last step is to create three text files under the gh-pages directory:
- The .nojekyll file, to tell Github not to process the files any further
- The CNAME file, because we serve the documentation under a custom domain
- The 404.html file, because the stock 404 page of Github can be confusing as the viewer does not usually expect it.
Now every time a change has to be made, we edit the proper files, issue
make html, commit and push the changes in both branches.
Not a lot of work, right?