Fix Read the Docs build, add Docker dev environment and standards sync

[jtdub]

Read the Docs

The build produced nothing usable. .readthedocs.yaml ran poetry install without pointing VIRTUAL_ENV at the environment Read the Docs runs mkdocs from, so Poetry created its own virtualenv and mkdocs was never installed where the build could find it. It also declared a second, conflicting install path via docs/requirements.txt.

Fixed by installing into $READTHEDOCS_VIRTUALENV_PATH and deleting docs/requirements.txt, leaving pyproject.toml as the single source of docs dependencies. Note this deliberately does not copy hier_config's simpler requirements-only approach: the mkdocstrings reference pages import hier_config_api, so the package itself has to be installed in the docs environment.

Docker development environment

Dockerfile is multi-stage — development carries the full toolchain, production only runtime dependencies. docker-compose.yml bind-mounts the repo for hot reload, with an opt-in docs profile for live-reload mkdocs on :8001.

Driven by invoke tasks (tasks.py), matching the task names used across the hier-config projects:

invoke build / serve / docs / pytest / lint / lint-and-test / cli / sync-standards / destroy

serve is this repo's addition to the shared set, since a library has no process to serve.

Shared standards

Adopts the model added in netdevops/hier_config#298. scripts/build.py, scripts/sync_standards.py, .yamllint.yml, and .dockerignore are now pulled from that repository via the .standards.yml manifest, with hier_config rewritten to hier_config_api as files are fetched. .github/workflows/sync-standards.yml applies the sync weekly and opens a PR, so CI validates canonical changes before they land.

⚠️ Depends on netdevops/hier_config#298 — the sync fetches from master, so sync-standards reports the new files as unpublished until that merges. Everything else here stands alone.

The ruff pin

Worth a careful look, as it is the largest behavioral change. This repo pinned ruff >=0.14.14,<0.15; the canonical repo tracks 0.16. That pin was the cause of the build.py divergence — ruff 0.14 does not understand the # ruff: ignore[...] directive the canonical file uses, so this repo's copy had been rewritten to # noqa and the two could never converge.

Relaxing to ^0.16 flips the relationship: under 0.16's preview rules that directive is not merely accepted but required, so the pre-existing # noqa comments in main.py and platform_service.py were converted. Also adds pytest-profiling for the --profile option the canonical build.py exposes.

With those aligned, invoke sync-standards reports zero drift on scripts/build.py.

Verification

• poetry run python scripts/build.py lint — clean on ruff 0.16
• 51 tests pass, 96% coverage (gate is 95%)
• poetry run mkdocs build --strict — clean
• Both Docker targets build; the dev container serves /api/openapi.json
• poetry run python scripts/sync_standards.py check — zero drift on the already-published files

🤖 Generated with Claude Code