Step 2: Deployment¶
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.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.
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.
Customization¶
Command line options¶
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 (--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. 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 the 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.
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, write_index_html=False in the doctr-versions-menu.conf configuration file).
Maintenance on gh-pages¶
Unless --no-write-index-html is given, 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.
