I read a few blog posts about how to use Github Pages to host Sphinx documentation, but it seemed to me they didn't quite capture just how easy this is to set up. So I'm going to document my setup procedure here in case that's helpful to others. It's probably easier to just show you how to do it, than to explain Github Pages , Sphinx, etc. etc. I'll document how I did this for my ReLaTeX project.
First I create a directory where I'll make Sphinx generate its HTML output, e.g.:
$ mkdir ~/projects/gh-pages $ mkdir ~/projects/gh-pages/relatex $ cd ~/projects/gh-pages/relatex $ git init $ git remote add origin git@github.com:cjlee112/relatex.git
where git@github.com:cjlee112/relatex.git is the address of the Github repository for my project that I'm building the docs for.
Next I add a make rule for generating HTML to the directory I just created, by editing the Sphinx Makefile in my original project directory (in my case that's in ~/projects/relatex/doc/Makefile). I added the following lines:
GHPAGES = gh-pages
gh_pages:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(GHPAGES)
@echo
@echo "Build finished. The HTML pages are in $(GHPAGES)."
Then add an appropriate symbolic link, and generate the HTML:
$ cd ~/projects/relatex/doc $ ln -s ~/projects/gh-pages/relatex gh-pages $ make gh_pages
Finally, we just need to push this to a new branch called gh-pages:
$ cd ~/projects/gh-pages/relatex $ touch .nojekyll $ git add . $ git commit -m 'docs built from relatex commit 782352' $ git checkout -b gh-pages $ git branch -d master $ git push origin gh-pages
My docs then showed up (after about 15 minutes) at http://cjlee112.github.io/relatex/ (substitute your Github username and project name).
For doc updates in the future, all you have to do is the make, git add, git commit and git push steps.
