WIP: some additions

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

Author: henryiii

README.md

@@ -336,6 +336,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

@@ -64,11 +64,14 @@ Ideally, software documentation should include:
 
 <!-- [[[cog
 from cog_helpers import code_fence, render_cookie, Matcher
-with render_cookie() as package:
+with render_cookie(backend="hatch", docs="sphinx") as package:
     docs_conf_py = package.joinpath("docs/conf.py").read_text(encoding="utf-8").strip()
     docs_index_md = package.joinpath("docs/index.md").read_text(encoding="utf-8").strip()
     readthedocs_yaml = package.joinpath(".readthedocs.yaml").read_text(encoding="utf-8").strip()
     noxfile = Matcher.from_file(package / "noxfile.py")
+with render_cookie(backend="hatch", docs="sphinx") as package:
+    noxfile_mkdocs = Matcher.from_file(package / "noxfile.py")
+    readthedocs_yaml_mkdocs = package.joinpath(".readthedocs.yaml").read_text(encoding="utf-8").strip()
 ]]] -->
 <!-- [[[end]]] -->
 
@@ -494,7 +497,7 @@ build:
 
 <!-- [[[cog
 with code_fence("yaml"):
-    print(readthedocs_yaml)
+    print(readthedocs_yaml_mkdocs)
 ]]] -->
 <!-- prettier-ignore-start -->
 ```yaml
@@ -591,7 +594,7 @@ autobuild will rebuild if you change a file while serving.
 
 <!-- [[[cog
 with code_fence("python"):
-    print(noxfile.get_source("docs"))
+    print(noxfile_mkdocs.get_source("docs"))
 ]]] -->
 <!-- prettier-ignore-start -->
 ```python

noxfile.py

@@ -15,6 +15,7 @@
 import difflib
 import email.parser
 import email.policy
+import enum
 import functools
 import json
 import os
@@ -36,6 +37,11 @@
 nox.options.default_venv_backend = "uv|virtualenv"
 
 
+class Docs(enum.Enum):
+    Sphinx = "sphinx"
+    MkDocs = "mkdocs"
+
+
 DIR = Path(__file__).parent.resolve()
 with DIR.joinpath("cookiecutter.json").open() as f:
     BACKENDS = json.load(f)["backend"]
@@ -45,6 +51,7 @@
   project_name: cookie-{backend}
   backend: {backend}
   vcs: {vcs}
+  docs: {docs}
 """
 
 
@@ -64,7 +71,7 @@ def get_expected_version(backend: str, vcs: bool) -> str:
     return "0.2.3" if vcs and backend not in {"maturin", "mesonpy", "uv"} else "0.1.0"
 
 
-def make_copier(session: nox.Session, backend: str, vcs: bool) -> Path:
+def make_copier(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> Path:
     package_dir = Path(f"copy-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
@@ -84,20 +91,21 @@ def make_copier(session: nox.Session, backend: str, vcs: bool) -> Path:
         "[email protected]",
         "--data=license=BSD",
         f"--data=vcs={vcs}",
+        f"--data=docs={docs.value}",
     )
 
     init_git(session, package_dir)
 
     return package_dir
 
 
-def make_cookie(session: nox.Session, backend: str, vcs: bool) -> Path:
+def make_cookie(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> Path:
     package_dir = Path(f"cookie-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
 
     Path("input.yml").write_text(
-        JOB_FILE.format(backend=backend, vcs=vcs), encoding="utf-8"
+        JOB_FILE.format(backend=backend, vcs=vcs, docs=docs.value), encoding="utf-8"
     )
 
     session.run(
@@ -112,7 +120,7 @@ def make_cookie(session: nox.Session, backend: str, vcs: bool) -> Path:
     return package_dir
 
 
-def make_cruft(session: nox.Session, backend: str, vcs: bool) -> Path:
+def make_cruft(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> Path:
     package_dir = Path(f"cruft-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
@@ -122,7 +130,8 @@ def make_cruft(session: nox.Session, backend: str, vcs: bool) -> Path:
 
     session.cd(tmp_dir)
     Path("input.yml").write_text(
-        JOB_FILE.format(backend=backend, pkg=package_dir, vcs=vcs), encoding="utf-8"
+        JOB_FILE.format(backend=backend, pkg=package_dir, vcs=vcs, docs=docs),
+        encoding="utf-8",
     )
     session.run(
         "cruft",
@@ -187,14 +196,15 @@ def diff_files(p1: Path, p2: Path) -> bool:
 
 
 @nox.session(default=False)
+@nox.parametrize("docs", list(Docs), ids=[d.value for d in Docs])
 @nox.parametrize("vcs", [False, True], ids=["novcs", "vcs"])
 @nox.parametrize("backend", BACKENDS, ids=BACKENDS)
-def lint(session: nox.Session, backend: str, vcs: bool) -> None:
+def lint(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> None:
     session.install("cookiecutter", "pre-commit")
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, vcs)
+    cookie = make_cookie(session, backend, vcs, docs)
     session.chdir(cookie)
 
     session.run(
@@ -213,22 +223,23 @@ def autoupdate(session: nox.Session, backend: str) -> None:
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, True)
+    cookie = make_cookie(session, backend, True, Docs.Sphinx)
     session.chdir(cookie)
 
     session.run("pre-commit", "autoupdate")
     session.run("git", "diff", "--exit-code", external=True)
 
 
 @nox.session(default=False)
+@nox.parametrize("docs", list(Docs), ids=[d.value for d in Docs])
 @nox.parametrize("vcs", [False, True], ids=["novcs", "vcs"])
 @nox.parametrize("backend", BACKENDS, ids=BACKENDS)
-def tests(session: nox.Session, backend: str, vcs: bool) -> None:
+def tests(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> None:
     session.install("cookiecutter")
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, vcs)
+    cookie = make_cookie(session, backend, vcs, docs)
     session.chdir(cookie)
 
     name = f"cookie-{backend}"
@@ -247,14 +258,15 @@ def tests(session: nox.Session, backend: str, vcs: bool) -> None:
 
 
 @nox.session(default=False)
+@nox.parametrize("docs", list(Docs), ids=[d.value for d in Docs])
 @nox.parametrize("vcs", [False, True], ids=["novcs", "vcs"])
 @nox.parametrize("backend", ("poetry", "pdm", "hatch"), ids=("poetry", "pdm", "hatch"))
-def native(session: nox.Session, backend: str, vcs: bool) -> None:
+def native(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> None:
     session.install("cookiecutter", backend)
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, vcs)
+    cookie = make_cookie(session, backend, vcs, docs)
     session.chdir(cookie)
 
     if backend == "hatch":
@@ -268,14 +280,15 @@ def native(session: nox.Session, backend: str, vcs: bool) -> None:
 
 
 @nox.session(default=False)
+@nox.parametrize("docs", list(Docs), ids=[d.value for d in Docs])
 @nox.parametrize("vcs", [False, True], ids=["novcs", "vcs"])
 @nox.parametrize("backend", BACKENDS, ids=BACKENDS)
-def dist(session: nox.Session, backend: str, vcs: bool) -> None:
+def dist(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> None:
     session.install("cookiecutter", "build", "twine")
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, vcs)
+    cookie = make_cookie(session, backend, vcs, docs)
     session.chdir(cookie)
 
     session.run("python", "-m", "build", silent=True)
@@ -331,14 +344,15 @@ def dist(session: nox.Session, backend: str, vcs: bool) -> None:
 
 
 @nox.session(name="nox", default=False)
+@nox.parametrize("docs", list(Docs), ids=[d.value for d in Docs])
 @nox.parametrize("vcs", [False, True], ids=["novcs", "vcs"])
 @nox.parametrize("backend", BACKENDS, ids=BACKENDS)
-def nox_session(session: nox.Session, backend: str, vcs: bool) -> None:
+def nox_session(session: nox.Session, backend: str, vcs: bool, docs: Docs) -> None:
     session.install("cookiecutter", "nox")
 
     tmp_dir = session.create_tmp()
     session.cd(tmp_dir)
-    cookie = make_cookie(session, backend, vcs)
+    cookie = make_cookie(session, backend, vcs, docs)
     session.chdir(cookie)
 
     if session.posargs:
@@ -356,13 +370,14 @@ def compare_copier(session):
 
     for backend in BACKENDS:
         for vcs in (False, True):
-            cookie = make_cookie(session, backend, vcs)
-            copier = make_copier(session, backend, vcs)
+            for docs in Docs:
+                cookie = make_cookie(session, backend, vcs, docs)
+                copier = make_copier(session, backend, vcs, docs)
 
-            if diff_files(cookie, copier):
-                session.log(f"{backend} {vcs=} passed")
-            else:
-                session.error(f"{backend} {vcs=} files are not the same!")
+                if diff_files(cookie, copier):
+                    session.log(f"{backend} {vcs=} passed")
+                else:
+                    session.error(f"{backend} {vcs=} files are not the same!")
 
 
 @nox.session(default=False)
@@ -374,13 +389,14 @@ def compare_cruft(session):
 
     for backend in BACKENDS:
         for vcs in (False, True):
-            cookie = make_cookie(session, backend, vcs)
-            cruft = make_cruft(session, backend, vcs)
-
-            if diff_files(cookie, cruft):
-                session.log(f"{backend} {vcs=} passed")
-            else:
-                session.error(f"{backend} {vcs=} files are not the same!")
+            for docs in Docs:
+                cookie = make_cookie(session, backend, vcs, docs)
+                cruft = make_cruft(session, backend, vcs, docs)
+
+                if diff_files(cookie, cruft):
+                    session.log(f"{backend} {vcs=} passed")
+                else:
+                    session.error(f"{backend} {vcs=} files are not the same!")
 
 
 PC_VERS = re.compile(

src/sp_repo_review/checks/readthedocs.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import yaml
 
-from .._compat.importlib.resources.abc import Traversable
 from . import mk_url
 
+if TYPE_CHECKING:
+    from .._compat.importlib.resources.abc import Traversable
+
 
 class ReadTheDocs:
     family = "docs"
@@ -102,6 +104,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)