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.

Quickstart

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:

The setup

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

language: python
python:
- '3.7'
- '3.8'
- 3.8-dev
- nightly
install:
- pip install -r dev-requirements.txt
script:
- make -C docs/ html
- touch docs/build/html/.nojekyll
deploy:
  - 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 build.py for Sphinx, that you may want to use to speed the process up:

import logging

import click
try:
    # Sphinx 1.7+
    from sphinx.cmd.build 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__)


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

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

    if not nowarn:
        args.append('-W')
    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:

Congratulations

You’ve done it, here’s a working example: that NASA is using, https://develop.larc.nasa.gov/.

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