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