This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

A tool for automatically deploying docs from Travis CI to GitHub pages.

Contribute to Doctr development on GitHub.

Installation

Install doctr with pip

pip install doctr

or conda

conda install -c conda-forge doctr

Note that doctr requires Python 3.5.

Usage

Run

doctr configure

and enter your data. You will need your GitHub username and password, and the repo you want to build the docs for.

That repo should already be setup with Travis. We recommend enabling branch protection for the gh-pages branch and other branches, as the deploy key used by Doctr has the ability to push to any branch in your repo.

Then add the stuff to your .travis.yml and commit the encrypted deploy key. The command above will tell you what to do. You should also have something like

language: python
python:
  - 3.5

sudo: false
env:
  global:
    secure: "<your secure key from doctr here>"

script:
  - pip install sphinx doctr
  - cd docs
  - make html
  - cd ..
  - doctr deploy

in your .travis.yml. See the one used by Doctr itself for example.

Heads up: 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.

Another suggestion: 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.

Note: 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>).

FAQ

  • 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 configure command 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 travis Ruby gem). The doctr deploy command 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?

    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.5, you will need to install Python 3.5 in Travis to run Doctr.

  • I would use this, but it’s missing a feature that I want.

    Doctr is still very new. We welcome all feature requests and pull requests.

  • 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!

Release History

Release History

1.4.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
doctr-1.4.0.tar.gz (29.4 kB) Copy SHA256 Checksum SHA256 Source Nov 11, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting