# 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.
## Installation
This package must be installed only during the Read the Docs build process, for example as an extra
requirement or through an additional requirements file.
__Example:__
```yaml
# .readthedocs.yml
version: 2
mkdocs:
configuration: "docs/mkdocs.yml"
python:
version: "3.7"
install:
- path: "."
extra_requirements: [ "rtd" ]
```
## How to use this?
RtdCS 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 either defined in `pyproject.toml` or in a file called
`.readthedocs-custom-steps.yml` (deprecated).
__Example:__
<table>
<tr>
<th><code>pyproject.toml</code></th>
<th><code>.readthedocs-custom-steps.yml</code></th>
</tr>
<tr>
<td>
```toml
[tool.readthedocs-custom-steps]
script = """
bash .scripts/generate-changelog.sh >docs/changelog.md
python -m "$@"
"""
```
</td>
<td>
```yml
steps:
- bash .scripts/generate-changelog.sh >docs/changelog.md
- python -m "$@"
```
</td>
</tr>
</table>
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 that is set before your script/steps are executed.
## Configuration
If a `pyproject.toml` exists and it contains a `[tool.readthedocs-custom-steps]` section, the configuration
will be read from there. Otherwise, a file called `.readthedocs-custom-steps.yml` must exist and will be
searched for in the following locations:
1. `.readthedocs-custom-steps.yml`
2. `docs/.readthedocs-custom-steps.yml`
3. 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, RtdCS 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).
---
<p align="center">Copyright © 2022 Niklas Rosenstein</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/NiklasRosenstein/readthedocs-custom-steps/",
"name": "readthedocs-custom-steps",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5.0,<4.0.0",
"maintainer_email": "",
"keywords": "",
"author": "Niklas Rosenstein",
"author_email": "rosensteinniklas@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/75/3f/e22bae7b7cf83042e4c22318cc5ae0cd04ac1f584186c073460a056a1a13/readthedocs-custom-steps-0.6.2.tar.gz",
"platform": "",
"description": "# readthedocs-custom-steps\n\nA hack to run custom steps when building documentation on Read the Docs.\n\n> __Important__: This module should not be installed outside of a Read the Docs build environment.\n> It will rename your Python executable and install a substitute. It does not currently provide an\n> automated way to revert this change.\n\n## Installation\n\nThis package must be installed only during the Read the Docs build process, for example as an extra\nrequirement or through an additional requirements file.\n\n__Example:__\n\n```yaml\n# .readthedocs.yml\nversion: 2\nmkdocs:\n configuration: \"docs/mkdocs.yml\"\npython:\n version: \"3.7\"\n install:\n - path: \".\"\n extra_requirements: [ \"rtd\" ]\n```\n\n## How to use this?\n\nRtdCS overrides your `python` installation with a Bash script that dispatches the\nexecution of custom steps upon invokation of `python -m mkdocs` or `python -m sphinx`.\nThe commands to run are either defined in `pyproject.toml` or in a file called\n`.readthedocs-custom-steps.yml` (deprecated).\n\n__Example:__\n\n<table>\n <tr>\n <th><code>pyproject.toml</code></th>\n <th><code>.readthedocs-custom-steps.yml</code></th>\n </tr>\n <tr>\n <td>\n\n```toml\n[tool.readthedocs-custom-steps]\nscript = \"\"\"\nbash .scripts/generate-changelog.sh >docs/changelog.md\npython -m \"$@\"\n\"\"\"\n```\n\n</td>\n <td>\n\n```yml\nsteps:\n- bash .scripts/generate-changelog.sh >docs/changelog.md\n- python -m \"$@\"\n```\n\n</td>\n </tr>\n</table>\n\n\nHere, `$@` contains the arguments after `python -m` in the Read the Docs build step, for example:\n\n* `mkdocs build --clean --site-dir _site/html --config-file mkdocs.yml`\n* `sphinx -T -b html -d _build/doctrees -D language=en . _build/html`\n\nAn infinite recursion of this script invoking itself in the example above is prevented automatically\nwith the `RTD_CUSTOM_ENTRY` environment variable that is set before your script/steps are executed.\n\n## Configuration\n\nIf a `pyproject.toml` exists and it contains a `[tool.readthedocs-custom-steps]` section, the configuration\nwill be read from there. Otherwise, a file called `.readthedocs-custom-steps.yml` must exist and will be\nsearched for in the following locations:\n\n1. `.readthedocs-custom-steps.yml`\n2. `docs/.readthedocs-custom-steps.yml`\n3. Relative to any directories from which requirements files are specified in the `.readthedocs.yml` file\n under the `$.python.install[*].requirements` configuration option.\n\n## Environment\n\nIn addition to passing the original arguments to the custom steps, RtdCS provides `PYTHON` environment variables\nas detected from the `~/.pyenv/shims` folder in the RTD build environment. (e.g. if there is a shim `python3.6` and\n`python3.7`, there'll be `PYTHON`, `PYTHON36` and `PYTHON37` environment variables, and `PYTHON` will point to 3.7).\n\n---\n\n<p align=\"center\">Copyright © 2022 Niklas Rosenstein</p>\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A hack to run custom steps when building documentation on Read the Docs.",
"version": "0.6.2",
"project_urls": {
"Homepage": "https://github.com/NiklasRosenstein/readthedocs-custom-steps/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "753fe22bae7b7cf83042e4c22318cc5ae0cd04ac1f584186c073460a056a1a13",
"md5": "37ad77fd9eb1b4a1a09e0614c1160dff",
"sha256": "7fbd57fa1faa533da7f3b3f504f9f11a58515e513b5480481dad59401b22ea4e"
},
"downloads": -1,
"filename": "readthedocs-custom-steps-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "37ad77fd9eb1b4a1a09e0614c1160dff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5.0,<4.0.0",
"size": 8146,
"upload_time": "2022-02-22T17:33:38",
"upload_time_iso_8601": "2022-02-22T17:33:38.023854Z",
"url": "https://files.pythonhosted.org/packages/75/3f/e22bae7b7cf83042e4c22318cc5ae0cd04ac1f584186c073460a056a1a13/readthedocs-custom-steps-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-02-22 17:33:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NiklasRosenstein",
"github_project": "readthedocs-custom-steps",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "readthedocs-custom-steps"
}
JSON
