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 steps: - bash .scripts/generate-changelog.sh >docs/changelog.md - python -m "[email protected]"
[email protected] 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
RTD_CUSTOM_ENTRY environment variable.
The file containing the steps must be a YAML file called
.readthedocs-custom-steps.yml. It is searched
for in the following locations:
- Relative to any directories from which requirements files are specified in the
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.7, there'll be
PYTHON37 environment variables, and
PYTHON will point to 3.7).