Table of Contents

Executive summary

pytest-notebook-policy has moved to a Great Docs-powered documentation workflow, alongside a Python 3.12+ baseline and a 1.0.0 major release to mark a stable foundation. The practical goal is straightforward: clearer docs, faster contributor onboarding, and lower maintenance overhead. Local docs authoring is now a short loop (build, preview, iterate), and early rollout link-validation issues are now handled through explicit pre-publish and strict workflows.

Why make this upgrade now

The package has grown beyond a “single README plus scattered notes” stage. The checks and reporting are useful, but discoverability and consistency matter just as much when teams adopt tooling.

As a long-time Quarto user, I also appreciated seeing Great Docs explicitly mentioned in Python Bytes Episode #484: All our tools. It was a useful external nudge that this stack is becoming more mainstream in practical Python workflows.

Great Docs provides a pragmatic middle path:

• fast setup with sensible defaults;
• API reference generation from real code;
• straightforward GitHub Pages deployment;
• LLM-facing outputs (llms.txt, llms-full.txt) as a built-in capability.

That combination keeps the docs workflow lightweight while still giving us structure.

What changed

At a high level, this upgrade includes:

1. Major release boundary

   • package version moved to 1.0.0.

2. Runtime baseline modernisation

   • minimum supported Python moved to 3.12+.

3. Great Docs integration

   • great-docs.yml added at repository root;
   • local docs build/preview commands wired into the workflow;
   • GitHub Pages docs workflow scaffolded for CI deployment.

4. CI alignment

   • test matrix updated to validate on Python 3.12 and 3.13.

5. Contributor ergonomics

   • just recipes added to self-document the docs workflow (docs-build, docs-preview, docs-check, docs-check-strict, docs-workflow).

What we found during rollout (and why it matters)

The first end-to-end docs checks were useful because they surfaced real operational details:

• branch-based source links can fail while work is still local/not published;
• GitHub Pages URLs can fail before the site is actually live;
• badges and external docs links can fail if URLs are stale.

This is exactly the kind of thing that turns “docs done” into hidden churn if not handled deliberately.

The practical fix was to define two gates:

1. Prepublish gate (just docs-workflow)

   • validates what should be stable during development;
   • ignores known not-yet-live endpoints.

2. Strict gate (just docs-workflow-strict)

   • no ignores;
   • intended for final validation when pages/remote links are live.

That split keeps the development loop fast without lowering standards for release-quality docs.

Why this matters for users and contributors

This is less about “prettier pages” and more about operational clarity:

• Faster onboarding: new users can move from install to meaningful usage with less context-hunting.
• Lower docs drift risk: generated API views reduce manual sync work.
• Clearer delivery path: docs build and deployment steps are explicit and repeatable.
• Better AI consumption: structured outputs improve package understanding for coding agents.

In short: fewer hidden docs chores, more time on actual quality policy improvements.

The practical workflow now

From the project root:

• run just docs-workflow during feature development;
• run just docs-preview for local authoring;
• run just docs-workflow-strict before/after publish hardening;
• publish via the docs workflow.

This keeps docs work close to code changes rather than as a trailing clean-up task.

Closing thoughts

I still favour an enforcement-lite stance in engineering practice: clear guardrails, proportionate gates, and fast feedback loops.

This docs upgrade follows the same philosophy. It raises quality and consistency without adding heavyweight process.

Source repository: github.com/DataBooth/pytest-notebook-policy
Great Docs project: posit-dev.github.io/great-docs