Hosting on GitHub Pages

You use GitHub Pages to host documentation generated by sphinx-multiversion.

Setting up the gh-pages Branch

First, you need to create a gh-pages branch and disable Jekyll.

git checkout --orphan gh-pages
touch .nojekyll
git add .nojekyll
git commit -m "Disable Jekyll"

Then, switch back to the branch you were on and build the documentation using sphinx-multiversion:

mkdir html
sphinx-multiversion docs/ html/

If everything worked fine, you now need to switch back to your gh-pages branch and commit the data there:

git checkout gh-pages
for dirname in html/*; do mv "html/$dirname" "$dirname" && git add "$dirname"; done
git commit -m "Added HTML docs"
git push origin gh-pages

Now your documentation should already be online. You can navigate to https://username.github.io/reponame/master/ to see the documentation for the master branch.

Redirecting from the Document Root

You can easily redirect users that type https://username.github.io/reponame/ into their addressbar to the documentation for any version you like. Just add a index.html file to the root directory of your gh-pages branch:

<!DOCTYPE html>
<html>
  <head>
    <title>Redirecting to master branch</title>
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url=./master/index.html">
    <link rel="canonical" href="https://username.github.io/reponame/master/index.html">
  </head>
</html>

Automating documentation builds with Travis CI

You can also automate versioned builds using Travis CI. To do that, add this to your .travis.yml file:

script:
  # Build documentation
- mkdir html
- sphinx-multiversion docs/ html/

before_deploy:
  # Add .nojekyll file and redirect from docroot to the sphinx output dir
- touch html/.nojekyll
- cp assets/gh-pages-redirect.html html/index.html

deploy:
  # Only deploy the sphinx output dir as gh-pages branch
- provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  keep_history: false
  local_dir: html

See also

For details, please have a look at the GitHub Pages Deployment documentation for Travis CI.