Documentation Hosting - goerz/cookiecutter-pypackage GitHub Wiki

ReadTheDocs (RTD) is the most widely used solution for hosting Sphinx documentation online. However, it injects "ethical ads" into the documentation.

Setup is straightforward:

• Create and account on RTD, and connect it to your Github account
• On https://readthedocs.org/dashboard/, click on "Import a Project" and select the project
• Add a file .readthedocs.yml to the root of your project containing e.g.

version: 2
formats:
    - htmlzip
build:
    image: latest
python:
    version: 3.7
    install:
        - method: pip
          path: .
          extra_requirements:
            - dev

See the RTD documentation for details. In the above example, the build-environment is initialized by running pip install .[dev] in the checkout of the Python package.

There is no way to control the build-process beyond the .readthedocs.yml file. In particular, it is not possible to specify arbitrary commands (make docs) to generate the documentation. Apart from advertisements, RTD also injects "Edit on Github" links to every page. These links tend to break for automatically generated (e.g. API) pages. Lastly, RTD injects a menu to switch between different versions of documentation. This is an extremely useful feature, except for the somewhat confusing "latest" and "stable" labels ("latest" is current development branch, not the latest release).

The RTD Sphinx theme is strongly recommended for all Sphinx documentations, and can be used wither or not the documentation is hosted on RTD. In particular, the RTD theme provides a much better visual structure than Sphinx' default alabaster theme.

Doctr is a tool uses the Travis Continuation Integration service (which you should be using to run your tests on every commit) to build and deploy documentation to Github Pages. These exist for every Github project: any static html documents on the "gh-pages branch of the repository are automatically available at http://<username>.github.io/<reponame>.

As pointed out in the Doctr FAQ, the main benefit of Doctr is the complete control over the build process, as Travis can run arbitrary code. Furthermore:

• No Advertisements
• No "Edit on Github" links

Disadvantages of Doctr:

• Since the gh-pages branch is part of the repository, using it to host the documentation can significantly increase the repository size. Some care must be taken not to push large binary objects (e.g. pdf versions of the documentation) for every commit. It may be necessary to perform some manual cleanup (git squash) on the gh-pages branch.
• No versions menu out of the box. However, this can be remedied with some custom code (eliminating the problems with RTD's versions menu)

See the Doctr documentation. Projects that use goerz/cookiecutter-pypackage should set up Doctr with

tox -e run-cmd -- doctr configure --no-upload-key --no-authenticate --key-path docs/doctr_deploy_key

Then,

• Set up the deploy key on Github (using the link printed by Doctr)
• Update the project's .travis.yml for the Docs task with the secure environment variable for the deploy key.
• Commit .travis.yml and docs/doctr_deploy_key.enc and push