Merge pull request #7538 from bensze01/in-tree-redirects

Add in-tree configuration file for Readthedocs redirects

.readthedocs.yaml

@@ -12,8 +12,14 @@ build:
     python: "3.9"
   jobs:
     pre_build:
-      - make apidoc
+    - make apidoc
-      - breathe-apidoc -o docs/api apidoc/xml
+    - 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:

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/

docs/requirements.in

@@ -1,2 +1,3 @@
-sphinx-rtd-theme
 breathe
+readthedocs-cli
+sphinx-rtd-theme

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