From 6fe50dee745a55757deabe2ef53d1a77bc34fce5 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 4 Jan 2024 19:10:14 +0100
Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D=F0=9F=92=85=20Use=20tox=20to?=
 =?UTF-8?q?=20build=20docs=20on=20RTD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .readthedocs.yaml | 36 ++++++++++++++++--------------------
 tox.ini           |  2 +-
 2 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 6964328dd..08529aa9c 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -4,30 +4,26 @@
 
 ---
 
-# Required
+# RTD API version
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  builder: dirhtml
-  configuration: docs/conf.py
-  fail_on_warning: true
-
-formats: []
-
-submodules:
-  include: all  # []
-  exclude: []
-  recursive: true
-
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: >-
+      3.10
+  commands:
+  - python -Im venv "${READTHEDOCS_VIRTUALENV_PATH}"
+  - >-
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    pip install tox
+  - >-
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e build-docs --notest -v
+  - >-
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e build-docs --skip-pkg-install -q
+    --
+    "${READTHEDOCS_OUTPUT}"/html
 
-# Optionally set the version of Python and requirements required
-# to build docs
-python:
-  install:
-  - requirements: docs/requirements.txt
 ...
diff --git a/tox.ini b/tox.ini
index 3a618f90a..853aad65d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -334,7 +334,7 @@ commands =
     -W --keep-going \
     -d "{temp_dir}/.doctrees" \
     . \
-    "{envdir}/docs_out"
+    {posargs:"{envdir}/docs_out"}
 
   # Print out the output docs dir and a way to serve html:
   -{envpython} -c\

From 901ac6e59ac3547fa33cfe537f1052082f2c80ba Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 4 Jan 2024 19:18:55 +0100
Subject: [PATCH 2/4] Make provisionoing tox venv @ RTD very verbose

---
 .readthedocs.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 08529aa9c..0f1b71ad0 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -19,7 +19,7 @@ build:
     pip install tox
   - >-
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
-    tox -e build-docs --notest -v
+    tox -e build-docs --notest -vvvvv
   - >-
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
     tox -e build-docs --skip-pkg-install -q

From 1258249a19ea045c20d342d51c011ca83a639545 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 4 Jan 2024 19:31:02 +0100
Subject: [PATCH 3/4] Move Sphinx build customization to env vars

---
 .readthedocs.yaml | 4 ++--
 tox.ini           | 8 ++++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 0f1b71ad0..51c5c810a 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -21,9 +21,9 @@ build:
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
     tox -e build-docs --notest -vvvvv
   - >-
+    SPHINX_BUILDER=dirhtml
+    SPHINX_BUILD_OUTPUT_DIRECTORY="${READTHEDOCS_OUTPUT}"/html
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
     tox -e build-docs --skip-pkg-install -q
-    --
-    "${READTHEDOCS_OUTPUT}"/html
 
 ...
diff --git a/tox.ini b/tox.ini
index 853aad65d..ce1c8cce3 100644
--- a/tox.ini
+++ b/tox.ini
@@ -326,15 +326,17 @@ commands =
 
   # Build the html docs with Sphinx:
   {envpython} -m sphinx \
+  {posargs:\
     -j auto \
-    -b html \
+    -b {env:SPHINX_BUILDER:html} \
     {tty:--color} \
     -a \
     -n \
     -W --keep-going \
     -d "{temp_dir}/.doctrees" \
     . \
-    {posargs:"{envdir}/docs_out"}
+    {env:SPHINX_BUILD_OUTPUT_DIRECTORY:"{envdir}/docs_out"} \
+  }
 
   # Print out the output docs dir and a way to serve html:
   -{envpython} -c\
@@ -350,6 +352,8 @@ commands =
 changedir = {toxinidir}/docs
 isolated_build = true
 passenv =
+  SPHINX_BUILDER
+  SPHINX_BUILD_OUTPUT_DIRECTORY
   SSH_AUTH_SOCK
 skip_install = true
 

From b25781360f308be1a6fee329047372de97586fc0 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 4 Jan 2024 19:32:51 +0100
Subject: [PATCH 4/4] Invoke docs runpy commands in isolation

---
 tox.ini | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tox.ini b/tox.ini
index ce1c8cce3..3cf0c78e1 100644
--- a/tox.ini
+++ b/tox.ini
@@ -325,7 +325,7 @@ commands =
   -git fetch --tags
 
   # Build the html docs with Sphinx:
-  {envpython} -m sphinx \
+  {envpython} -Im sphinx \
   {posargs:\
     -j auto \
     -b {env:SPHINX_BUILDER:html} \
@@ -346,7 +346,7 @@ commands =
   print("\n" + "=" * 120 +\
   f"\n\nDocumentation available under:\n\n\
   \tfile://\{index_file\}\n\nTo serve docs, use\n\n\
-  \t$ python3 -m http.server --directory \
+  \t$ python3 -Im http.server --directory \
   \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
   "=" * 120)'
 changedir = {toxinidir}/docs