From 4f4c87b01e99fb9fc62b5872cdb90d266bf01dbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Fri, 14 Apr 2023 15:00:27 +0200 Subject: [PATCH 1/5] Add readthedocs-cli to requirements.in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This will allow us to manage our redirects in-tree. Signed-off-by: Bence Szépkúti --- docs/requirements.in | 3 ++- docs/requirements.txt | 20 ++++++++++++++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) 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 From 7ce8fba3cbf2174917e1672ac557fbba3493a121 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Fri, 14 Apr 2023 16:36:19 +0200 Subject: [PATCH 2/5] Add post-build step to update redirects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This allows us to maintain the list of redirects in-tree. Signed-off-by: Bence Szépkúti --- .readthedocs.yaml | 7 +++++-- docs/redirects.yaml | 10 ++++++++++ 2 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 docs/redirects.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml index cef07bf1c..104ef7674 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,8 +12,11 @@ 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: + - '[ "$READTHEDOCS_VERSION" != "development" ] || "$READTHEDOCS_VIRTUALENV_PATH/bin/rtd" projects "Mbed TLS API" redirects sync --wet-run -f docs/redirects.yaml' + # 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..c3a13f302 --- /dev/null +++ b/docs/redirects.yaml @@ -0,0 +1,10 @@ +# Readthedocs redirects +# See https://docs.readthedocs.io/en/stable/user-defined-redirects.html +# +# In order to prevent exposing the API token, PR jobs do not update the +# redirects - changes to this file are only applied when they are merged +# into the main branch. + +- type: exact + from_url: /projects/api/en/latest/$rest + to_url: /projects/api/en/development/ From 6a89a04ffe3b63c40cefaa1f46152e4fda4a1fa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Tue, 9 May 2023 20:11:51 +0200 Subject: [PATCH 3/5] Use if statement for post_build control flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bence Szépkúti --- .readthedocs.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 104ef7674..a98bec72f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,8 +15,10 @@ build: - make apidoc - breathe-apidoc -o docs/api apidoc/xml post_build: - - '[ "$READTHEDOCS_VERSION" != "development" ] || "$READTHEDOCS_VIRTUALENV_PATH/bin/rtd" projects "Mbed TLS API" redirects sync --wet-run -f docs/redirects.yaml' - + - | + 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: From 09f8df86ac44ebe8b58ea3a78f222a4f9d3fc899 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Tue, 9 May 2023 20:47:49 +0200 Subject: [PATCH 4/5] Reword the API token explanation in redirects.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bence Szépkúti --- docs/redirects.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/redirects.yaml b/docs/redirects.yaml index c3a13f302..7ea1d9550 100644 --- a/docs/redirects.yaml +++ b/docs/redirects.yaml @@ -1,9 +1,10 @@ # Readthedocs redirects # See https://docs.readthedocs.io/en/stable/user-defined-redirects.html # -# In order to prevent exposing the API token, PR jobs do not update the -# redirects - changes to this file are only applied when they are merged -# into the main branch. +# 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 From 71f41deebc2d8ae946a1847f3bf43c81332f4f42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Tue, 9 May 2023 20:11:51 +0200 Subject: [PATCH 5/5] Work around Readthedocs command parsing bug MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bence Szépkúti --- .readthedocs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a98bec72f..2b38c07e0 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,6 +16,7 @@ build: - 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