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.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3b2064f0962f7ba03d5d4a2dd4480607e12390506b4cf53c63c3be9075c5d52c |
|
MD5 | e164adb4510290571d60734a4536080a |
|
BLAKE2b-256 | 96ce1dede0aa56ff2f024f5d0d534f5e821714c81142d1310e2b4ad17babf201 |