Hosting Sphinx Documentation on GitHub
As many other Python-based projects, we use Sphinx to document the various
components of Transifex.
During the last days, we wanted to decomission 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 shot 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 be? 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?