feat: add readthedocs config check (#545)

* feat: add readthedocs config check

Signed-off-by: Henry Schreiner <[email protected]>

* style: pre-commit fixes

---------

Signed-off-by: Henry Schreiner <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: henryiii

README.md

@@ -317,6 +317,7 @@ for family, grp in itertools.groupby(collected.checks.items(), key=lambda x: x[1
 - [`RTD101`](https://learn.scientific-python.org/development/guides/docs#RTD101): You have to set the RTD version number to 2
 - [`RTD102`](https://learn.scientific-python.org/development/guides/docs#RTD102): You have to set the RTD build image
 - [`RTD103`](https://learn.scientific-python.org/development/guides/docs#RTD103): You have to set the RTD python version
+- [`RTD104`](https://learn.scientific-python.org/development/guides/docs#RTD104): You have to specify a build configuration now for readthedocs.
 
 ### GitHub Actions
 - [`GH100`](https://learn.scientific-python.org/development/guides/gha-basic#GH100): Has GitHub Actions config

docs/pages/guides/docs.md

@@ -319,7 +319,8 @@ modern Ubuntu should be fine) {% rr RTD102 %}, a `tools` table (we'll use Python
 {% rr RTD103 %}, several languages are supported here).
 
 Adding a `sphinx` table tells Read the Docs to enable Sphinx integration. MkDocs
-is supported too.
+is supported too. You must include one of these unless you use build commands
+{% rr RTD104 %}.
 
 Finally, we have a `python` table with an `install` key to describe how to
 install our project. This will enable our "docs" extra.

pyproject.toml

@@ -164,7 +164,6 @@ extend-select = [
 ]
 ignore = [
   "PLR",    # Design related pylint codes
-  "PT004",  # Incorrect check, usefixtures is the correct way to do this
   "RUF012", # Would require a lot of ClassVar's
 ]
 
@@ -180,5 +179,5 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "src/sp_repo_review/_compat/**.py" = ["TID251"]
 
-[tool.repo-review]
-ignore = ["RTD103"]
+[tool.repo-review.ignore]
+RTD103 = "Using Ruby instead of Python for docs"

src/sp_repo_review/checks/readthedocs.py

@@ -100,6 +100,34 @@ def check(readthedocs: dict[str, Any]) -> bool:
                 return False
 
 
+class RTD104(ReadTheDocs):
+    "You have to specify a build configuration now for readthedocs."
+
+    requires = {"RTD100"}
+
+    @staticmethod
+    def check(readthedocs: dict[str, Any]) -> bool:
+        """
+        You must set `sphinx: configuration:`, `mkdocs: configuration:` or
+        `build: commands:`. Skipping it is no longer allowed. Example:
+
+        ```yaml
+        sphinx:
+          configuration: docs/conf.py
+        ```
+        """
+
+        match readthedocs:
+            case {"build": {"commands": list()}}:
+                return True
+            case {"sphinx": {"configuration": str()}}:
+                return True
+            case {"mkdocs": {"configuration": str()}}:
+                return True
+            case _:
+                return False
+
+
 def readthedocs(root: Traversable) -> dict[str, Any]:
     for path in (".readthedocs.yaml", ".readthedocs.yml"):
         readthedocs_path = root.joinpath(path)

tests/test_readthedocs.py

@@ -0,0 +1,91 @@
+from pathlib import Path
+
+import pytest
+import yaml
+from repo_review.testing import compute_check
+
+
+@pytest.mark.parametrize("readthedocs", [".readthedocs.yml", ".readthedocs.yaml"])
+def test_rtd100(tmp_path: Path, readthedocs: str) -> None:
+    simple = tmp_path / "simple"
+    simple.mkdir()
+    simple.joinpath(readthedocs).touch()
+    assert compute_check("RTD100", root=simple).result
+
+
+def test_rtd101_true() -> None:
+    readthedocs = yaml.safe_load("""
+        version: 2
+    """)
+    assert compute_check("RTD101", readthedocs=readthedocs).result
+
+
+def test_rtd101_false() -> None:
+    readthedocs = yaml.safe_load("""
+        other: 2
+    """)
+    assert not compute_check("RTD101", readthedocs=readthedocs).result
+
+
+def test_rtd102_true() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+          os: ubuntu-22.04
+    """)
+    assert compute_check("RTD102", readthedocs=readthedocs).result
+
+
+def test_rtd102_false() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+          python: "3.12"
+    """)
+    assert not compute_check("RTD102", readthedocs=readthedocs).result
+
+
+def test_rtd103_true() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+          tools:
+            python: "3.12"
+    """)
+    assert compute_check("RTD103", readthedocs=readthedocs).result
+
+
+def test_rtd103_false() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+          os: ubuntu-22.04
+    """)
+    assert not compute_check("RTD103", readthedocs=readthedocs).result
+
+
+def test_rtd104_commands() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+          commands: []
+    """)
+    assert compute_check("RTD104", readthedocs=readthedocs).result
+
+
+def test_rtd104_sphinx() -> None:
+    readthedocs = yaml.safe_load("""
+        sphinx:
+          configuration: docs/conf.py
+    """)
+    assert compute_check("RTD104", readthedocs=readthedocs).result
+
+
+def test_rtd104_mkdocs() -> None:
+    readthedocs = yaml.safe_load("""
+        mkdocs:
+          configuration: docs/mkdocs.yml
+    """)
+    assert compute_check("RTD104", readthedocs=readthedocs).result
+
+
+def test_rtd104_false() -> None:
+    readthedocs = yaml.safe_load("""
+        build:
+    """)
+    assert not compute_check("RTD104", readthedocs=readthedocs).result