ENH: set sphinx.configuration (#488)

* FIX: avoid installing `sphinx-codeautolink==0.16.0`

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",
 ]

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)

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

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

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

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

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