Auto deploying docs to GitHub Pages with Travis CI

auto_deploy_docs.md

Auto-Deploying Documents to GitHub Pages with Travis CI

There is already some gists talks about this topic using bash. However, Travis now support deploy in .travis.yml , which is super easy to set up. (Deploying to GitHub Pages is experimental now [2018.07.25])

I will show you an example of Python & Sphinx.

Create .travis.yml File

Here is a python example.

language: python

python:
  - "3.5"

install:
  - pip install -r requirements.txt
  - pip install -r requirements_docs.txt
  - pip install -e .

script:
  - python -m unittest

after_success:
  - cd docs && make html

deploy:
  provider: pages
  skip-cleanup: true
  keep-history: true
  on:
    branch: master
  github-token: $GITHUB_TOKEN
  local-dir: docs/build/html
  committer-from-gh: true

For the details about deploy , check Travis docs .

You may need to create a requirements_docs.txt file like this:

sphinx>=1.7.6
sphinx-rtd-theme>=0.4.0

shpinx-rtd-theme is optimal.

Remember to add sphinx.ext.githubpages to your conf.py file, this extension will create .nojekyll file which is used to disable GitHub Pages gem build.

For now, you have already done most of the work.

Set GitHub Token

To push files to your repo@gh-pages , Travis needs your authority. This means you need to offer a personal GitHub token.

You can choose to set this in travis-ci.org/repo/settings as an environment variable or pass it to .travis.yml as an encrypted variable.

Create GitHub Tokens

Open https://github.com/settings/tokens and click Generate new token . Just select repo is enough. You can get details from GitHub Help .

Travis Environment Variable

This can be set in your repo's travis page, More options -> settings , or just add /settings to the URL.

The variable name should be the same with github-token in .travis.yml .

Encrypted Variables

This requires Ruby and gem. If you don't want to install these, just use the last method.

Details can be found in Travis Docs .

Finally

Deploying is triggered depending on your repo's travis settings.