From 5016341893bb56fa4d10bf352e9d49545e480db3 Mon Sep 17 00:00:00 2001
From: Remco de Boer <29308176+redeboer@users.noreply.github.com>
Date: Mon, 13 Jan 2025 15:11:42 +0100
Subject: [PATCH] ENH: set `sphinx.configuration` (#488)

* FIX: avoid installing `sphinx-codeautolink==0.16.0`
---
 pyproject.toml                                |  1 +
 .../check_dev_files/readthedocs.py            | 25 +++++++++++++++++--
 .../readthedocs/extend/.readthedocs-bad.yml   |  2 ++
 .../readthedocs/extend/.readthedocs-good.yml  |  2 ++
 .../overwrite/.readthedocs-bad1.yml           |  2 ++
 .../overwrite/.readthedocs-bad2.yml           |  2 ++
 .../overwrite/.readthedocs-good.yml           |  2 ++
 7 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 16013295..c1e46744 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -379,4 +379,5 @@ description = "Perform all linting, formatting, and spelling checks"
 [tool.uv]
 constraint-dependencies = [
     "pygments!=2.19.*", # https://github.com/felix-hilden/sphinx-codeautolink/issues/152
+    "sphinx-codeautolink!=0.16.0",
 ]
diff --git a/src/compwa_policy/check_dev_files/readthedocs.py b/src/compwa_policy/check_dev_files/readthedocs.py
index 99fcc4fb..f7f7ac27 100644
--- a/src/compwa_policy/check_dev_files/readthedocs.py
+++ b/src/compwa_policy/check_dev_files/readthedocs.py
@@ -11,7 +11,7 @@
 
 from compwa_policy.errors import PrecommitError
 from compwa_policy.utilities import CONFIG_PATH, get_nested_dict
-from compwa_policy.utilities.match import git_ls_files
+from compwa_policy.utilities.match import filter_files, git_ls_files
 from compwa_policy.utilities.pyproject import get_constraints_file
 from compwa_policy.utilities.yaml import create_prettier_round_trip_yaml
 
@@ -32,6 +32,7 @@ def main(
     if isinstance(source, Path) and not source.exists():
         return
     rtd = ReadTheDocs(source)
+    _set_sphinx_configuration(rtd)
     _update_os(rtd)
     _update_python_version(rtd, python_version)
     if package_manager == "pixi+uv":
@@ -51,6 +52,27 @@ def main(
     rtd.finalize()
 
 
+def _set_sphinx_configuration(config: ReadTheDocs) -> None:
+    if "sphinx" not in config.document:
+        config.document["sphinx"] = {}
+    sphinx = config.document["sphinx"]
+    if "configuration" not in sphinx:
+        conf_path = __get_sphinx_config_path()
+        sphinx["configuration"] = str(conf_path)
+        msg = f"Set sphinx.configuration to {conf_path}"
+        config.changelog.append(msg)
+
+
+def __get_sphinx_config_path() -> Path | None:
+    conf_path = Path("docs/conf.py")
+    if conf_path.exists():
+        return conf_path
+    candidate_paths = list(filter_files(["**/conf.py"]))
+    if not candidate_paths:
+        return None
+    return Path(candidate_paths[0])
+
+
 def _update_os(config: ReadTheDocs) -> None:
     build = cast("CommentedMap", config.document.get("build"))
     if build is None:
@@ -150,7 +172,6 @@ def _remove_redundant_settings(config: ReadTheDocs) -> None:
         "build.apt_packages",
         "build.jobs",
         "formats",
-        "sphinx",
     ]
     removed_keys = [
         key for key in redundant_keys if __remove_nested_key(config.document, key)
diff --git a/tests/check_dev_files/readthedocs/extend/.readthedocs-bad.yml b/tests/check_dev_files/readthedocs/extend/.readthedocs-bad.yml
index a4783463..e5fba45c 100644
--- a/tests/check_dev_files/readthedocs/extend/.readthedocs-bad.yml
+++ b/tests/check_dev_files/readthedocs/extend/.readthedocs-bad.yml
@@ -12,3 +12,5 @@ build:
       - mkdir bin
       - ln -s $PWD/julia-1.9.2/bin/julia bin/julia
       - ./bin/julia docs/InstallIJulia.jl
+sphinx:
+  configuration: docs/conf.py
diff --git a/tests/check_dev_files/readthedocs/extend/.readthedocs-good.yml b/tests/check_dev_files/readthedocs/extend/.readthedocs-good.yml
index aac24f4c..a65344a6 100644
--- a/tests/check_dev_files/readthedocs/extend/.readthedocs-good.yml
+++ b/tests/check_dev_files/readthedocs/extend/.readthedocs-good.yml
@@ -13,3 +13,5 @@ build:
       - mkdir bin
       - ln -s $PWD/julia-1.9.2/bin/julia bin/julia
       - ./bin/julia docs/InstallIJulia.jl
+sphinx:
+  configuration: docs/conf.py
diff --git a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad1.yml b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad1.yml
index beaf95f6..c6a7c8d0 100644
--- a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad1.yml
+++ b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad1.yml
@@ -6,3 +6,5 @@ build:
   jobs:
     post_install:
       - pip install -e .[doc]
+sphinx:
+  configuration: docs/conf.py
diff --git a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad2.yml b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad2.yml
index cfad009f..68ea541b 100644
--- a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad2.yml
+++ b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-bad2.yml
@@ -3,3 +3,5 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.7"
+sphinx:
+  configuration: docs/conf.py
diff --git a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-good.yml b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-good.yml
index 6474f98d..8ae999c4 100644
--- a/tests/check_dev_files/readthedocs/overwrite/.readthedocs-good.yml
+++ b/tests/check_dev_files/readthedocs/overwrite/.readthedocs-good.yml
@@ -7,3 +7,5 @@ build:
     post_install:
       - python -m pip install 'uv>=0.2.0'
       - python -m uv pip install -e .[doc]
+sphinx:
+  configuration: docs/conf.py