Step 2: Deployment¶
Command line options¶
Debugging¶
If the doctr-versions-menu command behaves unexpectedly, set the environment variable
DOCTR_VERSIONS_MENU_DEBUG=true
in your .travis.yml file, see --debug.
Make sure to include the debug output when reporting bugs.
Default assumptions¶
You should not have to customize doctr-versions-menu (that is, provide
command line options) provided you stick to the following sensible assumptions:
Releases should be tagged as e.g.
v0.1.0and deployed to a folder of the same name. That is, a lower case lettervfollowed by a PEP 440-compatible version identifier.The
masterbranch should be deployed to a foldermaster.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 public release (excluding pre-releases such as v1.0.0-rc1), or to
master if there have been no public releases. There is no support for an RTD-style
“latest”/”stable” folder. This is by design: deep-linking to “latest” documentation
is a bad practice, as such links easily become invalid when a new version is
released.
Customization¶
If you do need to customize doctr-versions-menu’s behavior, there are three options:
Set the various
DOCTR_VERSIONS_MENU_*environment variablesPlace a configuration file
doctr-versions-menu.confin the root of thegh-pagesbranchCall the
doctr-versions-menuexecutable with explicit command line options
Passing command line options¶
Lastly, you may also explicitly invoke the doctr-versions-menu executable with specific
Command line options in your .travis.yml, respectively the doctr_build.sh script.
For example, you might have the following deploy command:
python -m doctr deploy --key-path docs/doctr_deploy_key.enc \
--command='doctr-versions-menu --debug' \
--built-docs docs/_build/html --no-require-master \
--build-tags "$DEPLOY_DIR"
Note the quotes around --command’s argument.
Generally, the use of environment variables is more readable and easier to
maintain, so you should avoid using command line options as part of your
automated builds.
Download links¶
By default, doctr-versions-menu looks for a file _downloads inside each
folder on the gh-pages branch. Each line in this file should have the
markdown-like format [label]: url, e.g.
[html]: https://dl.bintray.com/goerz/doctr_versions_menu/doctr_versions_menu-v0.1.0.zip
These links will be shown in the versions menu in a section “Downloads”, using
the label as the link text. See Documentation Artifacts for further
information on how to build and upload the underlying files. The name of the
file can be changed via the DOCTR_VERSIONS_MENU_DOWNLOADS_FILE environment
variable (see --downloads-file).
If the _downloads file is missing, you will see a warning message during
the deploy. To disable use of a _downloads file (ignore existing files, and
don’t warn for missing files), set DOCTR_VERSIONS_MENU_DOWNLOADS_FILE to an
empty string (see --no-downloads-file).
Custom warning messages¶
By default, the Doctr Versions Menu plugin injects warnings in the rendered HTML files, within the following types of folders:
an ‘outdated’ warning for
<releases>older than the latest public release (identified by--latest)an ‘unreleased’ warning for
<branches>(anything that is not a PEP 440-conforming release), or<local-releases>(typically not used)a ‘prereleased’ warning for anything considered a pre-release by PEP 440, e.g.
v1.0.0-rc1
Which folders are included in the above three categories can be modified via the --warning option.
This options receives two arguments, a “warning label” string (the above
‘outdated’, ‘unreleased’, or ‘prereleased’), and a
folder specification for the
folders to which the warning should apply. The option can be given multiple
times. An empty specification would disable the warning, e.g.
doctr-versions-menu --warning prereleased ''
to disable the warning message on pre-releases.
It is also possible to define entirely new warning labels using --warning. For example,
doctr-versions-menu --warning post '<post-releases>'
would define a warning ‘post’ for all post-releases.
The information about which folders should display which warnings is stored
internally in the resulting versions.json file, in a dict ‘warnings’ the
maps folder names to a list of warning labels.
To actually show this new custom warning, the doctr-versions-menu.js_t
template would have to be modified to pick up on the ‘post’ label, see the
instructions for the Customization of the
doctr_versions_menu Sphinx extension.
Similarly to Labels in the versions menu, when configuring the warnings
via the DOCTR_VERSIONS_MENU_WARNING environment variable, multiple
--warning options are combined into a single value, separated by
semicolons, and the warning label and folder specification separated by a
colon.
For the above two options, you might include the following the definition of
the environment variables in the .travis.yml file:
- DOCTR_VERSIONS_MENU_WARNING: '''post: <post-relases>; prereleased:'''
The triple-quotes are required to protect the string from both YAML and shell interpolation.
In the config file, the above options may be configured as e.g.:
warning = '''[
('post', '<post-releases>'),
('prereleased', ''),
]'''
The default settings (with the default --latest) correspond to:
warning = '''[
('outdated', '(<releases> < (<public-releases>)[-1])'),
('unreleased', '<branches>, <local-releases>'),
('prereleased', '<pre-releases>'),
]'''
Note the triple-quotes required for a multi-line entry.
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 public release (--latest), or
master if no public 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 receiving a dict version_data containing the
data in versions.json (see the versions.json Structure).
The default template is
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Refresh" content="0; url={{ version_data['latest'] | default('master', true) }}" />
</head>
<body>
<p>Go to the <a href="{{ version_data['latest'] | default('master', true) }}">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, DOCTR_VERSIONS_MENU_WRITE_INDEX_HTML=false as an environment
variable or write_index_html=False in the doctr-versions-menu.conf configuration file).
Maintenance on gh-pages¶
Unless --no-write-versions-py is given or
DOCTR_VERSIONS_MENU_WRITE_VERSIONS_PY=false is set, running
doctr-versions-menu will generate a script versions.py in the root of
the gh-pages branch that may be used to regenerate the versions.json
file. This script is intended for manual maintenance on the gh-pages
branch, that is, outside of the normal automatic Doctr-deployment through
Travis. For example, you may occasionally want to remove folders for outdated
branches or pre-releases from the gh-pages branch, or update existing
download links.
After any such change, run the versions.py script before committing and
pushing the gh-pages branch.
Remember that each folder on the gh-pages branch generally contains its own
doctr-versions-menu.js script. Switching a project to a new major version
of doctr-versions-menu, if that version changes the internal data structure of
versions.json, may require updating the doctr-versions-menu.js script
in existing folders by hand.
