Skip to content

Add OpenBolt documentation#191

Merged
binford2k merged 8 commits into
OpenVoxProject:masterfrom
miharp:feat/openbolt-docs
May 14, 2026
Merged

Add OpenBolt documentation#191
binford2k merged 8 commits into
OpenVoxProject:masterfrom
miharp:feat/openbolt-docs

Conversation

@miharp
Copy link
Copy Markdown
Contributor

@miharp miharp commented May 13, 2026 •
edited
Loading

Summary

  • Adds OpenBolt 5.x documentation as a new Jekyll collection (openbolt_latest / openbolt_5x)
  • 50 static documentation pages moved from the openbolt repo to docs/_openbolt_5x/, with .html cross-reference links, a local release notes page, and a collection index
  • 9 reference pages (command reference, plan functions, transports, etc.) are generated at CI time by rake references:openbolt, which clones the openbolt repo and runs rake docs:all to render ERB templates
  • Adds PuppetReferences::Openbolt::Docs class following the same PuppetReferences framework pattern as openvox/openfact (ref: Add OpenBolt documentation #143)
  • Wires into puppet_references.rb, Rakefile, and CI build.yaml
  • Adds OpenBolt feature card to homepage

Details

Collection routing

docs/_openbolt_latest is a symlink → docs/_openbolt_5x. Pages are served at /openbolt/latest/:path and /openbolt/5.x/:path. The collection defaults set layout: default and nav: openbolt_5x for all pages.

Sidebar nav

_data/nav/openbolt_5x.yml is a hand-authored nav tree derived from the original bolt.ditamap structure. All links are local .html references. The original external GitHub CHANGELOG link has been replaced with a local release_notes.md page matching the style of other collections.

CI-generated reference pages

references:openbolt clones openvoxproject/openbolt to vendor/openbolt, runs bundle exec rake docs:all inside it, then copies the 9 generated .md files to docs/_openbolt_5x/. These 9 files are listed in docs/_openbolt_5x/.gitignore so they are never committed.

Companion PR

Depends on OpenVoxProject/openbolt#233, which removes static docs and DITA from the openbolt repo and adds the rake docs:all task (with Jekyll front matter in ERB templates) that this PR relies on.

Out of scope

OpenVoxProject/openbolt#234 tracks removal of the upgrading_to_bolt_3 page, which is Puppet Bolt legacy content not relevant to OpenBolt users. That will be a follow-up PR.

Test plan

  • bundle exec jekyll build succeeds with no errors or unknown-collection warnings
  • All 60 pages (50 static + 9 generated + index) at /openbolt/latest/ render as .html
  • /openbolt/latest/ index page renders the OpenBolt 5 overview
  • All sidebar nav links resolve to existing pages
  • Homepage feature card links to /openbolt/latest/
  • After openbolt#233 merges: bundle exec rake references:openbolt INSTALLPATH=docs generates 9 reference pages with front matter

@miharp miharp requested a review from a team as a code owner May 13, 2026 14:39
@miharp miharp mentioned this pull request May 13, 2026
Merged
5 tasks
@miharp miharp force-pushed the feat/openbolt-docs branch from 0a43abd to 3a3814a Compare May 13, 2026 15:22
@miharp
Add OpenBolt documentation to openvox-docs (#232)
7f9612b 
Adds OpenBolt 5.x documentation as a new Jekyll collection. Static
documentation pages are moved here from the openbolt repo; 9 reference
pages (bolt_command_reference, plan_functions, etc.) are generated at
CI time by running `rake references:openbolt`, which clones the openbolt
repo and invokes `rake docs:all` to render ERB templates.

- Add `openbolt_latest` / `openbolt_5x` Jekyll collections with layout
  and sidebar nav defaults, nav-map routing, and `docs/_openbolt_latest`
  symlink → `docs/_openbolt_5x`
- Add 50 static documentation pages including collection index, release
  notes, and 49 pages moved from openbolt, with `.html` cross-reference links
- Add `PuppetReferences::Openbolt::Docs` class that runs `rake docs:all`
  in the vendored openbolt repo and copies the 9 generated reference pages
- Wire into `puppet_references.rb`, `Rakefile`, and CI `build.yaml`
- Add OpenBolt feature card to homepage

Depends on OpenVoxProject/openbolt#233, which adds `rake docs:all` and
updates ERB templates with Jekyll front matter.

Signed-off-by: Michael Harp <mike@mikeharp.com>
@miharp miharp force-pushed the feat/openbolt-docs branch from 3a3814a to 7f9612b Compare May 13, 2026 15:23
@miharp miharp marked this pull request as draft May 13, 2026 15:24
@miharp
Copy link
Copy Markdown
Contributor Author

miharp commented May 13, 2026

The markdown-lint check is failing with 1205 errors across the static documentation pages in docs/_openbolt_5x/. These are pre-existing style issues inherited from the original Puppet Bolt documentation source — trailing spaces, missing code fence languages, list marker spacing, etc. — and are not introduced by this PR.

Could a maintainer either mark the markdown-lint check as non-required for this PR, or advise on the preferred approach for handling legacy content that doesn't meet the current lint standards? We can track cleanup as a follow-up.

@miharp miharp marked this pull request as ready for review May 13, 2026 15:32
@tuxmea
Copy link
Copy Markdown
Contributor

tuxmea commented May 13, 2026

The markdown-lint check is failing with 1205 errors across the static documentation pages in docs/_openbolt_5x/. These are pre-existing style issues inherited from the original Puppet Bolt documentation source — trailing spaces, missing code fence languages, list marker spacing, etc. — and are not introduced by this PR.

Could a maintainer either mark the markdown-lint check as non-required for this PR, or advise on the preferred approach for handling legacy content that doesn't meet the current lint standards? We can track cleanup as a follow-up.

I am fine with manually marking linter as non-required.
But I also prefer to have at least one more collaborator to approve this.

@jay7x
Copy link
Copy Markdown
Contributor

jay7x commented May 14, 2026

I'm fine to merge as-is as well.

jay7x
jay7x reviewed May 14, 2026
View reviewed changes
Comment thread Rakefile Outdated
puts 'The following references are available:'
puts 'bundle exec rake references:openvox [VERSION=<GIT TAG OR COMMIT> INSTALLPATH=<RELATIVE OR ABSOLUTE PATH>]'
puts 'bundle exec rake references:openfact [VERSION=<GIT TAG OR COMMIT> INSTALLPATH=<RELATIVE OR ABSOLUTE PATH>]'
puts 'bundle exec rake references:openbolt [INSTALLPATH=<RELATIVE OR ABSOLUTE PATH>]'
Copy link
Copy Markdown
Contributor

@jay7x jay7x May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall we support setting VERSION also here? It's just like replacing 'main' with ENV['VERSION'] I guess..

binford2k
binford2k requested changes May 14, 2026
View reviewed changes
Comment thread docs/_openbolt_5x/analytics.md Outdated
miharp added 2 commits May 14, 2026 08:59
@miharp
Remove analytics page — pipeline non-functional upstream
7262588 
The OpenBolt analytics pipeline is broken (openbolt#235) and the page
will be removed from the source repo. Drop it here per reviewer request
and remove the corresponding nav entry.

Signed-off-by: Michael Harp <mike@mikeharp.com>
@miharp
Merge remote-tracking branch 'upstream/master' into feat/openbolt-docs
885ecc3
@miharp @claude
Merge upstream/master — add OpenVox Containers alongside OpenBolt
df8d792 
Keep both the OpenBolt entries (from this branch) and the new
OpenVox Containers section added upstream in _config.yml,
_data/nav_map.yml, _data/navigation.yml, and index.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miharp miharp requested a review from binford2k May 14, 2026 17:25
miharp and others added 2 commits May 14, 2026 14:27
@miharp
Merge remote-tracking branch 'upstream/master' into feat/openbolt-docs
af66f0a
@miharp @claude
Add VERSION support to references:openbolt rake task
0f1e280 
Aligns openbolt with openvox/openfact: accepts a VERSION env var,
falls back to the latest git tag via repo.describe, and prints
"Using tag …" for visibility.

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miharp miharp requested review from jay7x and tuxmea May 14, 2026 18:53
@miharp @claude
Add markdownlint overrides for imported OpenBolt docs
9c5022c 
Suppresses 1205 pre-existing lint violations inherited from upstream
Puppet Bolt source. Each rule is documented with its violation count.
Tracked for cleanup in issue OpenVoxProject#199.

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miharp
Copy link
Copy Markdown
Contributor Author

miharp commented May 14, 2026

To address the markdown-lint CI failures: added docs/_openbolt_5x/.markdownlint.yaml which suppresses the 1205 pre-existing violations inherited from the upstream Puppet Bolt source. Each disabled rule is documented with its violation count so we have a clear picture of the cleanup scope. Tracked for follow-up in #199.

@tuxmea
Copy link
Copy Markdown
Contributor

tuxmea commented May 14, 2026 •
edited
Loading

@binford2k can you please review your change request to this pr?

@binford2k binford2k merged commit c5c938a into OpenVoxProject:master May 14, 2026
4 checks passed
@miharp miharp deleted the feat/openbolt-docs branch May 15, 2026 10:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tuxmea tuxmea tuxmea approved these changes

@binford2k binford2k binford2k approved these changes

@jay7x jay7x Awaiting requested review from jay7x

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@miharp @tuxmea @jay7x @binford2k