Step 2: Deployment¶
Deployment with Github Actions¶
As of December 2020, Travis ended their support for open source software. Thus, it is no longer possible to use Doctr as originally intended and as described throughout this documentation. The recommended alternative for all continous integration (including building documentation) is to use Github Actions. Doctr may add support for Github Actions in the future. In the meantime, for basic use cases (deploying the documentation to the gh-pages branch of the same repository), it is quite straightforward to implement the deployment “by hand”. A possible workflow is the following:
Build the documentation, zip the resulting html and upload it as an artifact
In a second job within the same workflow:
Check out the
gh-pagesbranchDownload the artifact generated by the first job and unpack it to a temporary location
Synchronize the unpacked html files with the appropriate subfolder within the
gh-pagesbranchRun the
doctr-versions-menucommandCommit and push the changes.
What makes this easy within Github Actions, is that the action is automatically authenticated to upload/download artifacts and to have push-access to the underlying repository. Thus, Doctr’s main feature of managing the deploy key for Travis becomes obsolete.
An example workflow file illustrates this in more detail.
If you are not using Travis/Doctr, you probably also want to change the menu title, by putting e.g.
doctr_versions_menu_conf = {
'menu_title': 'Docs' # instead of 'Doctr'
}
in your conf.py file.
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, respectivelymainto a foldermainfor projects that use “main” as the default branch name.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
the default branch (main or 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
the default branch (see --default-branch) 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(version_data['default-branch']) | default(version_data['folders'][0], true) }}" />
</head>
<body>
<p>Go to the <a href="{{ version_data['latest'] | default(version_data['default-branch']) | default(version_data['folders'][0], 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.
