Skip to content

ci: publish generated manual editions as release assets - #256

Open
somethingwithproof wants to merge 1 commit into
developfrom
docs/manuals-release-assets
Open

somethingwithproof wants to merge 1 commit into
developfrom
docs/manuals-release-assets

Conversation

@somethingwithproof

Copy link
Copy Markdown
Member

Stacked on #248.

Every documentation change currently has to rebuild and commit the generated manuals. Generated text pins its links to the source commit, so even a one-line Markdown fix rewrites the 39 MB development PDF, eight companion PDFs and nine text editions. A two-line correction in #248 touched 20 files.

This PR keeps the existing build and verification and changes only where the results go:

  • PDF and text manual editions still builds and verifies every edition on each pull request and on develop.
  • After a push to develop (or a manual run on develop), a separate publish job uploads the 21 verified outputs to a fixed manuals-develop prerelease, replacing the previous assets. That job has contents: write, runs no repository code, and only downloads the verified artifact. The build job keeps its read-only token.
  • The generated files under resource/manuals/, plus resource/pdf/cacti-manual.pdf and its manifest, are removed from Git and ignored.
  • Downloads.md, Other-Manuals.md, Development-and-Testing.md and the publication guide now link to the release assets.
  • The ReportIt PDFs remain committed because their editable source is not in this repository.

Asset names are the current file names. The two manifests are renamed to cacti-manual-manifest.json and editions-manifest.json because release assets share a single namespace.

The release links return 404 until the first publish runs after merge. Running the workflow once on develop fills them immediately. Mirroring the editions on files.cacti.net is still a separate maintainer step.

Validation, run from a clean checkout of this branch:

  • All 38 Python tests and the navigation check pass.
  • The HTML manual builds.
  • All editions build and verify_other_manuals.py reports complete: true.
  • The staged asset set is exactly 21 files.

Base automatically changed from docs/manuals-refresh-develop to develop November 19, 2026 10:11
Committing the PDF and text editions put a 39 MB PDF and nine text
editions into every documentation change, and pinned links in the
generated text meant even a one-line Markdown fix rewrote all of them.

Build and verify the editions in CI as before, then upload them from a
separate job, which runs no repository code, to the manuals-develop
prerelease after each change to develop. Stop tracking the generated
outputs and point the download pages at the release assets. The
ReportIt PDFs stay committed because their editable source is not in
this repository.

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
@somethingwithproof
somethingwithproof force-pushed the docs/manuals-release-assets branch from b2c0817 to 67f1036 Compare November 19, 2026 10:18
@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant