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.
We recommend doctr a tool that configures Travis-CI to automatically publish your documentation every time the master branch is updated.
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.
python3 -m pip install --upgrade doctr
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
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
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.
<REDACTED> is replaced by the output you got from
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.
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.