Replace the bespoke code-reference generation script with a maintained plugin

[jvanderaa]

docs/generate_code_reference_pages.py is a bespoke script whose only job is to feed mkdocs-gen-files a list of modules. Maintained tooling does this with no script at all, and the script has already proven to be a place where defects hide: it globbed a non-existent directory for a long time and silently produced zero pages, which is what #425 / #434 turned up.

#434 deliberately leaves the generator untouched, so this is the follow-up that replaces it.

Two approaches remove it entirely. Both were built locally against the pinned toolchain (mkdocs 1.6.1, mkdocstrings 0.27.0) with the exact CI command from tasks.py:315, mkdocs build --no-directory-urls --strict.

Option A — mkdocstrings recurses on its own

Delete the script, drop the gen-files plugin from mkdocs.yml and mkdocs-gen-files from pyproject.toml, and add a five-line page:

# Code Reference

::: circuit_maintenance_parser
    options:
      show_submodules: true

Equivalent output to the current script: 60 module anchors, 34 parser modules, 559 KB vs 565 KB today. Net result is one fewer Python file and one fewer dependency.

Option B — mkdocs-api-autonav

Delete the script and swap mkdocs-gen-files for mkdocs-api-autonav. The plugin discovers the modules, writes the pages, and inserts its own nav section:

  - "api-autonav":
      modules: ["circuit_maintenance_parser"]
      nav_section_title: "Code Reference"

Produces 46 per-module pages with a full sidebar. api_root_uri defaults to reference and can be set to code-reference to keep existing URLs. Net result is one fewer Python file and no change in dependency count.

Recommendation

Option B. It removes the script, gives one page per module instead of a single 559 KB page, and costs no net dependency. Option A is the smaller change if per-module pages aren't wanted.

Worth noting for either: the per-module layout only builds under --strict when the generated pages are reachable from the nav. Fixing the module path alone produces 46 pages that aren't in nav, and mkdocs aborts on that warning. Option B handles the nav itself; Option A sidesteps it with a single page.

Upstream

This script comes from the python template in networktocode-llc/cookiecutter-ntc, and .cookiecutter.json has _drift_manager set to update-or-create against develop. Changing it only here means drift PRs will keep proposing the script back. The template's use of the wrong variable is already filed as networktocode-llc/cookiecutter-ntc#420; if we settle on an approach here it likely belongs upstream as well, so every repo baked from the template stops shipping the script.