Publishing the Documentation

In this section you will publish your documentation on a public website hosted by GitHub Pages.

This section assume you have already set up Travis-CI, as we covered in a previous section, Continous Integration Testing.

Configure Doctr

We recommend doctr a tool that configures Travis-CI to automatically publish your documentation every time the master branch is updated.

Warning

The repo you want to build the docs for has to be a root repo. You cannot build docs for a forked repo by doctr yet. The doctr team is working on enabling a forked repo build under PR #343.

Install doctr.

python3 -m pip install --upgrade doctr

Just type doctr configure and follow the prompts. Example:

$ doctr configure
Welcome to Doctr.

We need to ask you a few questions to get you on your way to automatically
deploying from Travis CI to GitHub pages.

What is your GitHub username? YOUR_GITHUB_USERNAME
Enter the GitHub password for YOUR_GITHUB_USERNAME:
A two-factor authentication code is required: app
Authentication code: XXXXXX
What repo do you want to build the docs for (org/reponame, like 'drdoctr/doctr')? YOUR_GITHUB_USERNAME/YOUR_REPO_NAME
What repo do you want to deploy the docs to? [YOUR_GITHUB_USERNAME/YOUR_REPO_NAME]

The deploy key has been added for YOUR_GITHUB_USERNAME/YOUR_REPO_NAME.

You can go to https://github.com/NSLS-II/NSLS-II.github.io/settings/keys to revoke the deploy key.

Then doctr shows some instructions, which we will take one at a time, elaborating here.

================== You should now do the following ==================

1. Add the file  github_deploy_key_your_github_username_your_repo_name.enc to be staged for commit:

    git add github_deploy_key_your_github_username_your_repo_name.enc

Remember that you can always use git status to list uncommitted files like this one.

2. Add these lines to your `.travis.yml` file:

    env:
      global:
        # Doctr deploy key for YOUR_GITHUB_USERNAME/YOUR_REPO_NAME
        - secure: "<REDACTED>"

    script:
    - set -e
    - <Command to build your docs>
    - pip install doctr
    - doctr deploy --built-docs <path/to/built/html/> <target-directory>

Replace the text in <angle brackets> with the relevant
things for your repository.

Note: the `set -e` prevents doctr from running when the docs build fails.
We put this code under `script:` so that if doctr fails it causes the
build to fail.

This output includes an encrypted token — the string next to secure: which I have redacted in the example above — that gives Travis-CI permission to upload to GitHub Pages.

Putting this together with the default .travis.yml file generated by the cookiecutter template, you’ll have something like:

# .travis.yml

language: python
python:
  - 3.6
cache:
  directories:
    - $HOME/.cache/pip
    - $HOME/.ccache  # https://github.com/travis-ci/travis-ci/issues/5853

env:
  global:
    # Doctr deploy key for YOUR_GITHUB_USERNAME/YOUR_REPO_NAME
    - secure: "<REDACTED>"

install:
  # Install this package and the packages listed in requirements.txt.
  - pip install .
  # Install extra requirements for running tests and building docs.
  - pip install -r requirements-dev.txt

script:
  - coverage run -m pytest  # Run the tests and check for test coverage.
  - coverage report -m  # Generate test coverage report.
  - codecov  # Upload the report to codecov.
  - flake8 --max-line-length=115  # Enforce code style (but relax line length limit a bit).
  - set -e  # If any of the following steps fail, just stop at that point.
  - make -C docs html  # Build the documentation.
  - pip install doctr
  - doctr deploy --built-docs docs/build/html .  # Publish the documentation.

where <REDACTED> is replaced by the output you got from doctr configure above.

3. Commit and push these changes to your GitHub repository.
The docs should now build automatically on Travis.

See the documentation at https://drdoctr.github.io/ for more information.

Once the changes are pushed to the master branch on GitHub, Travis-CI will publish the documentation to https://<YOUR_GITHUB_USERNAME>.github.io/<YOUR_REPO_NAME>. It may take a minute for the updates to process.

Alternatives

Another popular option for publishing documentation is https://readthedocs.org/ . We slightly prefer using Travis-CI + GitHub Pages because it is easier to debug any installation issues. It is also more efficient: we have to build the documentation on Travis-CI anyway to verify that any changes haven’t broken them, so we might as well upload the result and be done, rather than having readthedocs build them again.