.. _github_pages: ======================= 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. .. code-block:: bash 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``: .. code-block:: bash 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: .. code-block:: bash 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 :file:`index.html` file to the root directory of your ``gh-pages`` branch: .. code-block:: html Redirecting to master branch Automating documentation builds with Travis CI ============================================== You can also automate versioned builds using Travis CI. To do that, add this to your :file:`.travis.yml` file: .. code-block:: yaml 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 .. seealso:: For details, please have a look at the `GitHub Pages Deployment documentation for Travis CI `_. .. _github_pages_website: https://pages.github.com/ .. _travis_gh_pages_deployment: https://docs.travis-ci.com/user/deployment/pages/