From 9b0744cbbcede2b35eb8c458685cf81494a79cfa Mon Sep 17 00:00:00 2001
From: Lars Reimann <mail@larsreimann.com>
Date: Tue, 11 Jul 2023 10:23:33 +0200
Subject: [PATCH] docs: set `site_url` to fix broken 404 page on RTD (#5)

### Summary of Changes

The 404 page was previously not properly rendered on Read the Docs
(RTD). This PR overrides the build commands of RTD. While this makes the
404 page work properly, it also removes the RTD flyout to select a
version. For now, however, we deem the 404 page as more essential.

Once https://github.com/readthedocs/readthedocs.org/issues/8529 is done,
we can use the default build again to make everything work as expected.
---
 mkdocs.yml      |  2 ++
 readthedocs.yml | 22 +++++++++++++++-------
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index e6ae9de0..9cfacd8a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,8 @@
 site_name: Stub Generator
 repo_url: https://github.com/Safe-DS/Stub-Generator
 repo_name: Safe-DS/Stub-Generator
+edit_uri: edit/main/docs/
+site_url: !ENV READTHEDOCS_CANONICAL_URL
 
 nav:
   - Home:
diff --git a/readthedocs.yml b/readthedocs.yml
index a44150b2..cd0e3de4 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -4,13 +4,21 @@ build:
   os: ubuntu-22.04
   tools:
     python: '3.10'
-  jobs:
-    # https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
-    post_create_environment:
-      - pip install poetry
-      - poetry config virtualenvs.create false
-    post_install:
-      - poetry install --with docs
+  commands:
+    - pip install poetry
+    - poetry config virtualenvs.create false
+    - poetry install --with docs
+    - cat mkdocs.yml
+    - mkdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html --config-file mkdocs.yml
+# Once https://github.com/readthedocs/readthedocs.org/issues/8529 is fixed, replace the commands above with the
+# following to use the default RTD build steps again:
+#  jobs:
+#    # https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
+#    post_create_environment:
+#      - pip install poetry
+#      - poetry config virtualenvs.create false
+#    post_install:
+#      - poetry install --with docs
 
 mkdocs:
   configuration: mkdocs.yml