Welcome to the Doctr documentation!¶
A tool for automatically deploying docs from Travis CI to GitHub pages.
Contribute to Doctr development on GitHub.
Install doctr with pip
pip install doctr
conda install -c conda-forge doctr
Note that doctr requires Python 3.5 or newer.
Run doctr configure¶
First use doctr to generate the necessary key files so that travis can push to your gh-pages (or other) branch.
and enter your data. You will need your GitHub username and password, and the repo organization / name for which you want to build the docs.
Note: That repo should already be set up with Travis. We recommend enabling
gh-pages branch and other branches, as the deploy key
used by doctr has the ability to push to any branch in your repo.
Edit your travis file¶
Doctr will output a bunch of text as well as instructions for next steps. You
need to edit your
.travis.yml with this text. It contains the secure key
that lets travis communicate with your github repository, as well as the
code to run (in
script:) in order to build the docs and deploy doctr.
.travis.yml file should look something like this:
# doctr requires python >=3.5 language: python python: - 3.6 # This gives doctr the key we've generated sudo: false env: global: secure: "<your secure key from doctr here>" # This is the script to build the docs on travis, then deploy script: - set -e - pip install sphinx doctr - cd docs - make html - cd .. - doctr deploy .
See the travis config file used by Doctr itself for example.
Note: You can deploy
doctrto a different folder by giving it a different path in the call to
doctr deploy docs/.
Warning: Be sure to add
script, to prevent
doctrfrom running when the docs build fails.
doctr deploy .in the
scriptsection of your
.travis.yml. If you use
after_success, it will not cause the build to fail.
Commit your new files and build your site¶
doctr configure will create a new file that contains your key. Commit this as
well as the changes to
.travis.yml. Once you push to github, travis should
now automatically build your documentation and deploy it.
Doctr requires Python 3.5 or newer. Be sure to run it in a Python 3.5 or newer section of your build matrix. It should be in the same build in your build matrix as your docs build, as it reuses that.
To force an error on warnings if you use Sphinx, add
html: SPHINXOPTS += -W
to your Sphinx
Makefile. This will make Sphinx error even if there are
warnings, keeping your docs more accurate.
Doctr does not require Sphinx. It will work with deploying anything to
GitHub pages. However, if you do use Sphinx, doctr will find your Sphinx
docs automatically (otherwise use
doctr deploy . --built-docs <DOCS PATH>).
Why did you build this?
Deploying to GitHub pages from Travis is not amazingly difficult, but it’s difficult enough that we wanted to write the code to do it once. We found that Travis docs uploading scripts are cargo culted and done in a way that is difficult to reproduce, especially the do-once steps of setting up keys. The
doctr configurecommand handles key generation automatically, and tells you everything you need to do to set Doctr up. It is also completely self-contained (it does not depend on the
travisRuby gem). The
doctr deploycommand handles key decryption (for deploy keys) and hiding tokens from the command output (for personal access tokens).
Furthermore, most Travis deploy guides that we’ve found recommend setting up a GitHub personal access token to push to GitHub pages. GitHub personal access tokens grant read/write access to all public GitHub repositories for a given user. A more secure way is to use a GitHub deploy key, which grants read/write access only to a single repository. Doctr creates a GitHub deploy key by default (although the option to use a token exists if you know what you are doing).
Why not Read the Docs?
Read the Docs is great, but it has some limitations:
- You are limited in what you can install in Read the Docs. Travis lets you run arbitrary code, which may be necessary to build your documentation.
- Read the Docs deploys to readthedocs.io. Doctr deploys to GitHub pages. This is often more convenient, as your docs can easily sit alongside other website materials for your project on GitHub pages.
In general, you should already be building your docs on Travis anyway (to test that they build), so it seems natural to deploy them from there.
Why does Doctr require Python 3.5 or newer?
There are several language features of Python that we wanted to make use of that are not available in earlier versions of Python, such as keyword-only arguments, subprocess.run, and recursive globs. These features help keep the Doctr code cleaner and more maintainable.
If you cannot build your documentation in Python 3, you will need to install Python 3.6 in Travis to run Doctr.
I would use this, but it’s missing a feature that I want.
Why is it called Doctr?
Because it deploys documentation from Travis. And it makes you feel good.
Projects using Doctr¶
Are you using doctr? Please add your project to the list!
- Doctr Command Line Help
- Doctr Changelog
- GitHub Test Authentication