A hack to run custom steps when building documentation on Read the Docs.
Project description
readthedocs-custom-steps
A hack to run custom steps when building documentation on Read the Docs.
Important: This module should not be installed outside of a Read the Docs build environment. It will rename your Python executable and install a substitute. It does not currently provide an automated way to revert this change.
How to use this?
Rtd-cs overrides your python
installation with a Bash script that dispatches the
execution of custom steps upon invokation of python -m mkdocs
or python -m sphinx
.
The commands to run are defined in a file called .readthedocs-custom-steps.yml
.
Example:
# .readthedocs-custom-steps.yml
steps:
- bash .scripts/generate-changelog.sh >docs/changelog.md
- python -m "$@"
Here, $@
contains the arguments after python -m
in the Read the Docs build step, for example:
mkdocs build --clean --site-dir _site/html --config-file mkdocs.yml
sphinx -T -b html -d _build/doctrees -D language=en . _build/html
An infinite recursion of this script invoking itself in the example above is prevented automatically
with the RTD_CUSTOM_ENTRY
environment variable.
Configuration
The file containing the steps must be a YAML file called .readthedocs-custom-steps.yml
. It is searched
for in the following locations:
.readthedocs-custom-steps.yml
docs/.readthedocs-custom-steps.yml
- Relative to any directories from which requirements files are specified in the
.readthedocs.yml
file under the$.python.install[*].requirements
configuration option.
Environment
In addition to passing the original arguments to the custom steps, Rtd-cs provides PYTHON
environment variables
as detected from the ~/.pyenv/shims
folder in the RTD build environment. (e.g. if there is a shim python3.6
and
python3.7
, there'll be PYTHON
, PYTHON36
and PYTHON37
environment variables, and PYTHON
will point to 3.7).
Copyright © 2021 Niklas Rosenstein
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for readthedocs-custom-steps-0.5.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 107d466a5c3c62c27bf191549ea3ce9fd94532c348ef2b0f04608e0c6c910d57 |
|
MD5 | 7ecaa1b1be50a559dde29b12f90e7f41 |
|
BLAKE2b-256 | e014a2c38d2ed39811ffd70a2d4cbf12358d3e87012096aad51e5e0d173bbe23 |