Using Sphinx and Travis CI Together for Seamless Documentation


Sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reStructuredText or Markdown documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more. Let’s integrate Travis CI for automatic document generation and making life a lot easier when both are bein used in conjunction.


Let’s install Sphinx using the CLI:

pip install --user travis-sphinx
export PATH=$HOME/.local/bin:$PATH

Make sure you have a gh-pages branch:

git checkout -b gh-pages
git rm -rf .
git push --set-upstream origin gh-pages

You’ll then need to get an access_token from GitHub - so you’ll need to generate a token to use. Head over to your GitHub account settings:

Screen Shot 2021-07-30 at 11 45 46 AM

The setup

Given the things in this guide we have, the .travis.yml file will look a bit like this:

language: python
- '3.7'
- '3.8'
- 3.8-dev
- nightly
- pip install -r dev-requirements.txt
- make -C docs/ html
- touch docs/build/html/.nojekyll
  - provider: pypi
    user: "__token__"
    password: $PYPI_TOKEN
    skip_existing: true
  - provider: pages:git
    verbose: true
    token: $GITHUB_TOKEN
    edge: true
    local_dir: ./docs/build/html/
    keep_history: true

Now let’s set your env vars in the Travis CI GUI:


## Building

Here’s a sample for Sphinx, that you may want to use to speed the process up:

import logging

import click
    # Sphinx 1.7+
    from import build_main
    sphinx_version_at_least_1_7 = True
except AttributeError:
    from sphinx import build_main
    sphinx_version_at_least_1_7 = False

from .main import main

_logger = logging.getLogger(__name__)

    help="Build sphinx documentation."
    '-s', '--source',
    type=click.Path(dir_okay=True, file_okay=False, exists=True),
    help='Source directory of sphinx docs',
    '-n', '--nowarn',
    help='Do not error on warnings',
def build(ctx, source, nowarn):
    Build documentation from ``source``, placing built files in
    """'building documentation')
    outdir = ctx.obj['outdir']

    if sphinx_version_at_least_1_7:
        args = ['-b', 'html']
        args = ['-b html']

    if not nowarn:
    if build_main(args + [source, outdir]):
        raise click.ClickException("Error building sphinx doc")

Specifying a custom deployment repository

Now, to specify a custom deployment repository if you’re using a fork (which most people reading this might be), for working on documentation. To do so, under your Travis environment variables, use the following constant:

GH_REPO_SLUG = 'syntaf/fork-of-my-repo'

Here’s an example from Vim on how the config (the .travis.yml) looks currently from my machine:

Screen Shot 2021-07-30 at 12 00 13 PM


You’ve done it, here’s a working example: that NASA is using,

If you need any more resources or help, please email me personally at, or look at the official Sphinx documentation to get a better idea of the .travis.yml I have laid out above. Happy building!