Parameterize reference generation by target collection#326
Open
miharp wants to merge 1 commit into
Open
Conversation
The reference generators hardcoded their output dir (_<product>_latest, or _openbolt_5x for OpenBolt) and emitted canonical/body URLs at load time, so every build wrote into the current stable collection and linked to /latest. To support frozen historical docs and a new major version, builds must be able to target an arbitrary collection and emit URLs that match that version. - Add PuppetReferences.url_base_for to map a collection dir to its published URL base (e.g. _openvox_9x -> /openvox/9.x), splitting on the last underscore so hyphenated product names stay intact. - Thread a collection: argument through build_puppet_references / build_facter_references / build_openbolt_references into every generator, replacing the load-time OUTPUT_DIR constants with instance-level paths derived from the target collection. - Add Reference#localize_links to rewrite the target product's own /latest/ doc links to the version base (e.g. /openvox/8.x), applied in the type and functions generators. Cross-product links (a different product's /latest/) follow latest per the repo's linking policy; it is a no-op when building the latest collection. - Key the Strings JSON memoization by output path rather than a single global flag, so building more than one collection in one process generates each strings.json instead of skipping and reading a missing/stale file. - Fix an existing OpenFact bug: core_facts and facter_cli stamped /openvox/latest canonicals while writing into _openfact_*; they now derive the correct /openfact/... base. - Rakefile accepts COLLECTION=<dir> alongside VERSION=, defaulting per product to the prior hardcoded targets so CI behavior is unchanged. - Document the COLLECTION flag in CONTRIBUTING. An explicit VERSION already bypasses the prerelease filter (newest_release is only consulted when no VERSION is given), so a frozen version can be built from a prerelease tag. Verified with real end-to-end builds: OpenFact 5.6.1 into _openfact_5x and the default _openfact_latest; OpenVox 9.0.0-alpha1 into _openvox_9x (all generators, subdirs and intermediate JSON routed correctly, version-pinned canonicals); and OpenVox 8.28.0 into _openvox_8x confirming the type-preamble links resolve to /openvox/8.x with zero intra-product /openvox/latest links remaining. Part of OpenVoxProject#325. Co-Authored-By: Claude Opus 4.8 <[email protected]> Signed-off-by: Michael Harp <[email protected]>
miharp
force-pushed
the
docs/issue-325-reference-pinning
branch
from
ea906a5 to
4df6da6
Compare
tuxmea
reviewed
Jun 10, 2026
| def initialize(*) | ||
| @latest = '/openvox/latest/man' | ||
| super | ||
| @latest = "#{@latest}/man" |
Contributor
There was a problem hiding this comment.
do we still need the initialize?
| @latest = '/openvox/latest/yard' | ||
| super | ||
| @latest = "#{@latest}/yard" | ||
| end |
Contributor
There was a problem hiding this comment.
do we still need this? initialize was removed in other files.
| end | ||
|
|
||
| def self.build_openbolt_references(commit) | ||
| def self.build_openbolt_references(commit, collection: '_openbolt_5x') |
Contributor
There was a problem hiding this comment.
why do we have a different pattern here? all other generator use _latest instead of a version.
| require 'puppet_references' | ||
| PuppetReferences.build_openbolt_references(ENV.fetch('VERSION', nil)) | ||
| PuppetReferences.build_openbolt_references(ENV.fetch('VERSION', nil), collection: ENV.fetch('COLLECTION', '_openbolt_5x')) | ||
| end |
Contributor
There was a problem hiding this comment.
same here. all other use latest.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Make the reference generators able to build into an arbitrary target collection,
rather than always writing into the current stable collection. This is the first
step toward versioned docs (frozen historical versions + a new major line).
Why
Today each generator hardcodes its output dir (
_<product>_latest, or_openbolt_5xfor OpenBolt) and emits canonical URLs at load time, so every buildlands in the current stable collection. To freeze
_openvox_8xand build a new_openvox_9xfrom a different upstream tag, builds need to target a specificcollection and emit URLs that match that version.
Changes
PuppetReferences.url_base_forto map a collection dir to its published URLbase (e.g.
_openvox_9x→/openvox/9.x), splitting on the last underscore sohyphenated product names (
openvox-server) stay intact.collection:argument throughbuild_puppet_references/build_facter_references/build_openbolt_referencesinto every generator,replacing the load-time
OUTPUT_DIRconstants with instance-level paths derivedfrom the target collection.
core_factsandfacter_clistamped/openvox/latestcanonicals while writing into_openfact_*; they now derive thecorrect
/openfact/...base./<product>/latest/links (e.g. via the static type preamble), which would leak a frozen version's
pages back to latest. Add
Reference#localize_links, which rewrites only thetarget product's own
/latest/doc links to the version base, applied in the typeand functions generators. Cross-product links (a different product's
/latest/)are left to follow latest per the repo's linking policy, and it's a no-op when
building the latest collection.
strings.jsongeneration was memoizedwith a single global flag while its path is now per collection; building more than
one collection in one process would skip generation and read a missing/stale file.
Memoize by output path instead.
RakefileacceptsCOLLECTION=<dir>alongsideVERSION=, defaulting per productto the prior hardcoded targets so CI behavior is unchanged.
An explicit
VERSIONalready bypasses the prerelease filter (newest_releaseisonly consulted when no
VERSIONis given), so a frozen version can be built from aprerelease tag — no change needed there.
Validation
Ran real end-to-end builds (not just unit checks):
references:openfact VERSION=5.6.1 COLLECTION=_openfact_5x→ files land in_openfact_5x, canonical/openfact/5.x/....references:openfact VERSION=5.6.1(noCOLLECTION) →_openfact_latest,canonical
/openfact/latest/...(back-compat preserved + bug fixed).references:openvox VERSION=9.0.0-alpha1 COLLECTION=_openvox_9x→ all fivegenerators ran;
man/,types/,types_strings/subdirs and the intermediateJSON (
strings.json,type.json, …) all routed into_openvox_9x; everycanonical is
/openvox/9.x/...(0 stale/openvox/latestcanonicals);built_from_commitmatches the9.0.0-alpha1tag, confirming the prerelease build.references:openvox VERSION=8.28.0 COLLECTION=_openvox_8x→ the three type-preamblelinks resolve to
/openvox/8.xin bothtype.md(root) andtypes/overview.md(subdir), and zero intra-product
/openvox/latest/links remain in the build.localize_linksunit-checked: rewrites the own product's/latest/, preserves adifferent product's
/latest/(cross-product) and externalpuppet.com/.../latestlinks, and is a no-op for the latest collection.
rubocopclean; library loads; all generator classes instantiate with theexpected output dir and URL base.
Scope
This is the generator capability only. The
references:alltask that reads a_data/versions.ymlpin table, the cutover runbook, and the version selector arefollow-ups.
Part of #325.