fix: better and more generation, docs job improvement

.pre-commit-config.yaml

@@ -89,5 +89,5 @@ repos:
         name: Cog the pages
         language: python
         entry: cog -P -r -I ./helpers
-        files: "^docs/pages/guides/(packaging_compiled|docs).md|^copier.yml"
+        files: "^docs/pages/guides/(packaging_compiled|docs|tasks).md|^copier.yml"
         additional_dependencies: [cogapp, cookiecutter]

docs/pages/guides/coverage.md

@@ -89,7 +89,7 @@ enough for a simple testing suite, can be written as follows:
 
 ```yaml
 - name: Upload coverage report
-  uses: codecov/[email protected].0
+  uses: codecov/[email protected].4
 ```
 
 The lines above should be added after the step that runs your tests with the

docs/pages/guides/docs.md

@@ -36,11 +36,12 @@ Ideally, software documentation should include:
 > it if you are interested.
 
 <!-- [[[cog
-from cog_helpers import render_cookie
+from cog_helpers import code_fence, render_cookie, Matcher
 with render_cookie() 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.yml").read_text(encoding="utf-8").strip()
+    noxfile = Matcher.from_file(package / "noxfile.py")
 ]]] -->
 <!-- [[[end]]] -->
 
@@ -53,12 +54,11 @@ is our recommended starting point for `conf.py`:
 
 ### conf.py
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```python")
-print(docs_conf_py)
-print("```")
+with code_fence("python"):
+    print(docs_conf_py)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```python
 from __future__ import annotations
 
@@ -106,8 +106,8 @@ nitpick_ignore = [
 
 always_document_param_types = True
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 We start by setting some configuration values, but most notably we are getting
 the package version from the installed version of your package. We are listing
@@ -157,12 +157,11 @@ for more options.
 
 Your `index.md` file can start out like this:
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("````md")
-print(docs_index_md)
-print("````")
+with code_fence("md", width=4):
+    print(docs_index_md)
 ]]] -->
+<!-- prettier-ignore-start -->
 ````md
 # package
 
@@ -182,8 +181,8 @@ print("````")
 - {ref}`modindex`
 - {ref}`search`
 ````
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 You can put your project name in as the title. The `toctree` directive houses
 your table of contents; you'll list each new page you add inside that directive.
@@ -220,12 +219,11 @@ plugins and try to build against an uninstalled version of your project.
 In order to use <https://readthedocs.org> to build, host, and preview your
 documentation, you must have a `.reathedocs.yml` file {% rr RTD100 %} like this:
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```yaml")
-print(readthedocs_yaml)
-print("```")
+with code_fence("yaml"):
+    print(readthedocs_yaml)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
@@ -246,8 +244,8 @@ python:
       extra_requirements:
         - docs
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 This sets the readthedocs config version (2 is required) {% rr RTD101 %}.
 
@@ -265,6 +263,11 @@ install our project. This will enable our "docs" extra.
 
 Add a session to your `noxfile.py` to generate docs:
 
+<!-- [[[cog
+with code_fence("python"):
+    print(noxfile.get_source("docs"))
+]]] -->
+<!-- prettier-ignore-start -->
 ```python
 @nox.session(reuse_venv=True)
 def docs(session: nox.Session) -> None:
@@ -274,40 +277,62 @@ def docs(session: nox.Session) -> None:
 
     parser = argparse.ArgumentParser()
     parser.add_argument("--serve", action="store_true", help="Serve after building")
+    parser.add_argument(
+        "-b", dest="builder", default="html", help="Build target (default: html)"
+    )
     args, posargs = parser.parse_known_args(session.posargs)
 
-    session.install("-e.[docs]")
+    if args.builder != "html" and args.serve:
+        session.error("Must not specify non-HTML builder with --serve")
+
+    session.install(".[docs]")
     session.chdir("docs")
 
+    if args.builder == "linkcheck":
+        session.run(
+            "sphinx-build", "-b", "linkcheck", ".", "_build/linkcheck", *posargs
+        )
+        return
+
     session.run(
         "sphinx-build",
         "-n",  # nitpicky mode
-        "--keep-going",  # show all errors
         "-T",  # full tracebacks
+        "-W",  # Warnings as errors
+        "--keep-going",  # See all errors
         "-b",
-        "html",
+        args.builder,
         ".",
-        f"_build/html",
+        f"_build/{args.builder}",
         *posargs,
     )
 
     if args.serve:
         session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
         session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
 ```
+<!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 ## API docs
 
 To build API docs, you need to add the following nox job:
 
 ### noxfile.py additions
 
+<!-- [[[cog
+with code_fence("python"):
+    txt = noxfile.get_source("build_api_docs")
+    print(txt.replace("package", "<package-name-here>"))
+]]] -->
+<!-- prettier-ignore-start -->
 ```python
 @nox.session
 def build_api_docs(session: nox.Session) -> None:
     """
     Build (regenerate) API docs.
     """
+
     session.install("sphinx")
     session.chdir("docs")
     session.run(
@@ -320,6 +345,8 @@ def build_api_docs(session: nox.Session) -> None:
         "../src/<package-name-here>",
     )
 ```
+<!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 And you'll need this added to your `docs/index.md`:
 

docs/pages/guides/packaging_compiled.md

@@ -82,7 +82,7 @@ These tools all read the project table. They also have extra configuration
 options in `tool.*` settings.
 
 <!-- [[[cog
-from cog_helpers import render_cookie
+from cog_helpers import code_fence, render_cookie
 with render_cookie(backend="skbuild") as skbuild:
     skbuild_cmakelists_txt = skbuild.joinpath("CMakeLists.txt").read_text(encoding="utf-8").strip()
     skbuild_src_main_cpp = skbuild.joinpath("src/main.cpp").read_text(encoding="utf-8").strip()
@@ -102,12 +102,11 @@ with render_cookie(backend="maturin") as maturin:
 Example `CMakeLists.txt` file (using pybind11, so include `pybind11` in
 `build-system.requires` too):
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```cmake")
-print(skbuild_cmakelists_txt)
-print("```")
+with code_fence("cmake"):
+    print(skbuild_cmakelists_txt)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```cmake
 cmake_minimum_required(VERSION 3.15...3.26)
 project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
@@ -118,20 +117,19 @@ find_package(pybind11 CONFIG REQUIRED)
 pybind11_add_module(_core MODULE src/main.cpp)
 install(TARGETS _core DESTINATION ${SKBUILD_PROJECT_NAME})
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% tab meson Meson-python %}
 
 Example `meson.build` file (using pybind11, so include `pybind11` in
 `build-system.requires` too):
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```meson")
-print(mesonpy_meson_build)
-print("```")
+with code_fence("meson"):
+    print(mesonpy_meson_build)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```meson
 project(
   'package',
@@ -168,19 +166,18 @@ py.extension_module('_core',
     ]
 )
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% tab maturin Maturin %}
 
 Example `Cargo.toml` file:
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```toml")
-print(maturin_cargo_toml)
-print("```")
+with code_fence("toml"):
+    print(maturin_cargo_toml)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```toml
 [package]
 name = "package"
@@ -206,8 +203,8 @@ version = "0.18.1"
 # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8
 features = ["extension-module", "abi3-py38"]
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% endtabs %}
 
@@ -217,12 +214,11 @@ features = ["extension-module", "abi3-py38"]
 
 Example `src/main.cpp` file:
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```cpp")
-print(skbuild_src_main_cpp)
-print("```")
+with code_fence("cpp"):
+    print(skbuild_src_main_cpp)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```cpp
 #include <pybind11/pybind11.h>
 
@@ -253,19 +249,18 @@ PYBIND11_MODULE(_core, m) {
   )pbdoc");
 }
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% tab meson Meson-python %}
 
 Example `src/main.cpp` file:
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```cpp")
-print(mesonpy_src_main_cpp)
-print("```")
+with code_fence("cpp"):
+    print(mesonpy_src_main_cpp)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```cpp
 #include <pybind11/pybind11.h>
 
@@ -296,17 +291,16 @@ PYBIND11_MODULE(_core, m) {
   )pbdoc");
 }
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% tab maturin Maturin %}
 
-<!-- prettier-ignore-start -->
 <!-- [[[cog
-print("```rs")
-print(maturin_src_lib_rs)
-print("```")
+with code_fence("rs"):
+    print(maturin_src_lib_rs)
 ]]] -->
+<!-- prettier-ignore-start -->
 ```rs
 use pyo3::prelude::*;
 
@@ -332,8 +326,8 @@ fn _core(_py: Python, m: &PyModule) -> PyResult<()> {
     Ok(())
 }
 ```
-<!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
+<!-- [[[end]]] -->
 
 {% endtab %} {% endtabs %}