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.
