Publishing sphinx generated documents on github

Back when I started (2017-09-05) using sphinx for my github pages. I quickly googled and found a thread. However, the solutions they offered was not really what I was looking for.

So instead I will present how I did it.

Setting up your repository

First create the repository and place yourself in its directory. Also create an empty repository on your github.

git init github-user.github.io
cd github-user.github.io

After that, add your remote for your github repo. Create an empty commit and push it [1].

git remote add origin https://github.com/github-user/github-user.github.io
git commit --allow-empty "Inital commit"
git push --set-upstream origin master

Now move to another empty branch gh-pages. This branch will contain all the sphinx sources. Also add the first branch as a submodule at build/html [2].

git checkout --orphan gh-pages
git remote add https://github.com/github-user/github-user.github.io build/html

Creating your initial sphinx

Use the defaults from sphinx-quickstart except for the options explicitly shown below

sphinx-quickstart
...
> Separate source and build directories (y/n) [n]: y
...
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
...

After that, simply run

make html             # Or whatever the equivalance is on M$

Publishing method

When you have something you are satisfied with and ready to publish commit everything in submodule build/html first, then commit the remainders.

Committing

(cd build/html; git add .; git commit -m "$(date)")
git add .; git commit -m "First version of proj"

Publishing

(cd build/html; git push)
git push

Having a blast

Done!

References