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 to see the documentation for the master branch.

Redirecting from the Document Root

You can easily redirect users that type 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>
    <title>Redirecting to master branch</title>
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url=./master/index.html">
    <link rel="canonical" href="">

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:

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

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

  # 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.