Documentation build toolchain improvements and release metadata plumbing

[cofinoa]

Moderator

@cofinoa

Requirement Summary

The CF documentation build system should be robust, reproducible, and explicit about editorial state (DRAFT vs FINAL), release metadata, and tooling dependencies.

This ehancement doesn't require any change on the normative content.

Technical Proposal Summary

Introduce a set of improvements to the documentation build toolchain (Makefile, metadata wiring, optional environments, and basic tests) to make builds reproducible, diagnosable, and explicit about release state. This is a tooling and workflow enhancement only.

Benefits

• More robust and reproducible documentation builds.
• Clear separation between DRAFT and FINAL artifacts.
• Single source of truth for release metadata (version, date, DOI).
• Easier onboarding for contributors building the docs.
• Reduced risk of accidental inconsistencies in released artifacts.

Status Quo

Currently:

• The documentation build relies on implicit tool availability and environment assumptions.
• Release metadata (version, date, citation year) is spread across multiple places.
• It is easy to accidentally regenerate artifacts with inconsistent dates or metadata.
• There is no lightweight, integrated link-checking step.
• Build failures can be hard to diagnose.

Other mature documentation workflows increasingly treat build reproducibility and metadata plumbing as first-class concerns.

Associated pull request

#622

Detailed Proposal

This issue tracks the changes implemented in PR #622, which include:

• Refactoring the Makefile to make tool invocation more robust and overridable.
• Adding explicit tool checks with clear error messages.
• Introducing an optional environment.yml for reproducible Conda/Mamba builds.
• Adding a basic link checker (make test-links) using lychee.
• Updating README.md to document the documentation build workflow.
• Centralising release metadata in version.adoc, which becomes the single source of truth for:
  • CF version number
  • Canonical ISO release date
  • DOI (when defined)
• Wiring this metadata into the build so that DRAFT and FINAL builds are explicit and reproducible.

Current behaviour after these changes:

• A normal make produces a DRAFT document.
• A FINAL build is produced via:

  DOC_STATUS=FINAL make
  

• In FINAL mode:
  • The visible release date is derived from the canonical ISO release date.
  • The citation year is fixed from that date.
  • Draft-only metadata is suppressed.

Out of scope for this issue:

• Definition of the full CF release workflow (DRAFT -> RC -> FINAL).
• Branching or tagging conventions.
• Formal release governance.

Those topics are expected to be discussed separately, via th already opened Discussion:
https://github.com/orgs/cf-convention/discussions/449

All changes are tooling-only, backward-compatible, and do not modify the CF specification or conformance text.

[JonathanGregory]

@cofinoa Thanks for doing a lot of work on this, evident in the PR, and for opening the issue. I am sure these improvements will make the processes easier and the results better.

Please could you clarify whether the cff and zenodo files are expected to be regenerated when you merge a change that affects the author list? (Perhaps that doesn't belong in this issue).

Jonathan