diff --git a/.readthedocs.yaml b/.readthedocs.yaml index cef07bf1c..2b38c07e0 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,8 +12,14 @@ build: python: "3.9" jobs: pre_build: - - make apidoc - - breathe-apidoc -o docs/api apidoc/xml + - make apidoc + - breathe-apidoc -o docs/api apidoc/xml + post_build: + - | + # Work around Readthedocs bug: Command parsing fails if the 'if' statement is on the first line + if [ "$READTHEDOCS_VERSION" = "development" ]; then + "$READTHEDOCS_VIRTUALENV_PATH/bin/rtd" projects "Mbed TLS API" redirects sync --wet-run -f docs/redirects.yaml + fi # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/docs/redirects.yaml b/docs/redirects.yaml new file mode 100644 index 000000000..7ea1d9550 --- /dev/null +++ b/docs/redirects.yaml @@ -0,0 +1,11 @@ +# Readthedocs redirects +# See https://docs.readthedocs.io/en/stable/user-defined-redirects.html +# +# Changes to this file do not take effect until they are merged into the +# 'development' branch. This is because the API token (RTD_TOKEN) is not +# made available in PR jobs - preventing bad actors from crafting PRs to +# expose it. + +- type: exact + from_url: /projects/api/en/latest/$rest + to_url: /projects/api/en/development/ diff --git a/docs/requirements.in b/docs/requirements.in index a523188c3..14d618c79 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,2 +1,3 @@ -sphinx-rtd-theme breathe +readthedocs-cli +sphinx-rtd-theme diff --git a/docs/requirements.txt b/docs/requirements.txt index 4b9f3a6b3..a1bfd8237 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -14,6 +14,8 @@ certifi==2022.12.7 # via requests charset-normalizer==3.1.0 # via requests +click==8.1.3 + # via readthedocs-cli docutils==0.17.1 # via # breathe @@ -27,14 +29,28 @@ importlib-metadata==6.0.0 # via sphinx jinja2==3.1.2 # via sphinx +markdown-it-py==2.2.0 + # via rich markupsafe==2.1.2 # via jinja2 +mdurl==0.1.2 + # via markdown-it-py packaging==23.0 # via sphinx pygments==2.14.0 - # via sphinx + # via + # rich + # sphinx +pyyaml==6.0 + # via readthedocs-cli +readthedocs-cli==4 + # via -r requirements.in requests==2.28.2 - # via sphinx + # via + # readthedocs-cli + # sphinx +rich==13.3.5 + # via readthedocs-cli snowballstemmer==2.2.0 # via sphinx sphinx==4.5.0