Step 2: Deployment

doctr-versions-menu

The Doctr Versions Menu package includes a doctr-versions-menu executable. This executable should be invoked when deploying the documentation on Travis, through doctr deploy’s --command flag.

As the explicit purpose of the Doctr Versions Menu is to enable documentation for multiple versions of a package at the same time, you’ll likely want to invoke doctr deploy also with the --no-required-master and --build-tags options.

For example, your .travis.yml file might include the following for deploying previously built documentation:

if [ ! -z "$TRAVIS_TAG" ]; then DEPLOY_DIR="$TRAVIS_TAG"; else DEPLOY_DIR="$TRAVIS_BRANCH"; fi

doctr deploy --command=doctr-versions-menu --no-require-master --build-tags "$DEPLOY_DIR"

See the deploy-section of the Doctr Versions Menu’s doctr_build.sh script (which is sourced from .travis.yml) for a more detailed example.

The main purpose of the doctr-versions-menu command is to generate the versions.json file that the Sphinx extension relies on, in the root of the gh-pages branch.

Debugging

If the doctr-versions-menu command behaves unexpectedly, add the --debug flag as follows:

doctr deploy --command="doctr-versions-menu --debug" --no-require-master --build-tags "$DEPLOY_DIR"

Make sure to include the debug output when reporting bugs.

Default assumptions

You should not have to customize doctr-versions-menu provided you stick to the following sensible assumptions:

  • Releases should be tagged as e.g. v0.1.0 and deployed to a folder of the same name. That is, a lower case letter v followed by a PEP 440-compatible version identifier.

  • The master branch should be deployed to a folder master.

  • Any other branch for which documentation is to be deployed should go in a folder matching the branch name.

By default, the index.html file will forward to the documentation of the latest release (excluding pre-releases such as v1.0.0-rc1), or to master if there have been no releases. There is no support for an RTD-style “latest”/”stable” folder. This is a good thing: deep-linking to “latest” documentation is a bad practice, as such links easily become invalid when a new version is released.

Customization

doctr-versions-menu.conf configuration file

If you do need to customize doctr-versions-menu’s behavior, the recommended way to do so it to place a configuration file doctr-versions-menu.conf in the root of the gh-pages branch. This configuration file can contain definitions matching doctr-versions-menu’s Command line options, formatted according to Configobj’s unrepr mode.

Every long-form flag has a corresponding config file variable, obtained by replacing hyphens with underscores. For boolean flags, the variable name is derived from the first flag option.

For example, the settings

default_branch = "develop"
ensure_no_jekyll = False

correspond to --default-branch=develop and --ignore-no-jekyll.

Command line options

doctr-versions-menu

Generate version json file in OUTFILE.

Except for debugging, it is recommended to set options through the config file (doctr-versions-menu.conf in the current working directory) instead of via command line flags. Every long-form-flag has a corresponding config file variable, obtained by replacing hyphens with underscores (--default-branch → default_branch).

doctr-versions-menu [OPTIONS]

Options

--version

Show the version and exit.

--debug

enable debug logging

-o, --outfile <outfile>

File to which to write json data [default: versions.json]

--default-branch <default_branch>

The default folder if no stable release is found [default: master]

--write-index-html, --no-write-index-html

Whether to write an index.html that forwards to the latest release. In the config file, override this as write_index_html=False. [default: True]

--ensure-no-jekyll, --ignore-no-jekyll

Whether to check that a .nojekyll file exist and create it otherwise. In the config file, override this as ensure_no_jekyll=False. [default: True]

--downloads-file <downloads_file>

The name of the file inside of each folder from which to read the download links. Each line in the file must be of the form “[label]: url”. [default: _downloads]

--suffix-latest <suffix_latest>

Suffix for the label of the latest stable release. [default: (latest release)]

--suffix-unreleased <suffix_unreleased>

Suffix for development branches and pre-releases [default: (dev)]

-c, --config <config>

Read configuration from FILE. Each line in FILE should be of the form “variable = value” in Python syntax, with variable names corresponding to any long-form command line flag, e.g. default_branch = "develop" or ensure_no_jekyll = False. [default: doctr-versions-menu.conf]

Customizing index.html

By default, doctr-versions-menu generates an index.html file in the root of the gh-pages branch that redirects to the current “default folder”. This is the folder for the most current stable release, or master (respectively --default-branch) if no stable release exists.

The generated index.html file can be customized by placing an index.html_t Jinja template into the root of the gh-pages branch. This template will be rendered using the single variable default_folder.

The default template is

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Refresh" content="0; url={{default_folder}}" />
  </head>
  <body>
    <p>Go to the <a href="{{default_folder}}">default documentation</a>.</p>
  </body>
</html>

Alternatively, if you want a completely static index.html, you could also just add that file by hand and use --no-write-index-html (that is, write_index_html=False in the doctr-versions-menu.conf configuration file).