Document the provider and validate REFERENCE.md in CI (2.0.1) - #51
Draft
silug wants to merge 2 commits into
Draft
Conversation
- Inline puppet-strings/YARD documentation for the gpasswd provider: an expanded desc covering membership semantics plus method-level docs (parameters, returns, version-compat rationale) - Commit the generated REFERENCE.md and add a reference-docs CI job running rake validate:strings so it can never go stale - Note: the openvox-strings markdown generator parses providers but has no template to render them, so REFERENCE.md is currently header-only for this provider-only module; validate:strings will flag the file for regeneration as soon as that is fixed upstream Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XCnDsYaJDLiP8z8tafz9Tp
silug
marked this pull request as draft
July 24, 2026 19:13
Temporarily source openvox-strings from the add-provider-markdown branch on silug/openvox-strings, which teaches the markdown generator to render providers; REFERENCE.md now documents the gpasswd provider (description, membership semantics, and commands). Revert to the released gem once the change is merged and published upstream. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XCnDsYaJDLiP8z8tafz9Tp
silug
commented
Jul 27, 2026
| gem 'openvox', openvox_version | ||
| gem 'openvox-strings' | ||
| # TODO: revert to the released gem once provider rendering is merged upstream | ||
| gem 'openvox-strings', git: 'https://github.com/silug/openvox-strings', branch: 'add-provider-markdown' |
Contributor
Author
There was a problem hiding this comment.
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.
Follows up on #50: adds the inline documentation, a committed
REFERENCE.md, and areference-docsCI job runningbundle exec rake validate:strings.The important finding
REFERENCE.mdcame out empty for a structural reason, not a missing-comments reason: openvox-strings parses providers (providers: 1in its JSON output) but its markdown/REFERENCE generator has no provider template — every other component type has one (markdown/resource_type.rb,puppet_class.rb, …), providers are silently dropped. Since this module is provider-only, no amount of YARD gets content into REFERENCE.md with the current gem.What this PR does
desc(membership semantics,auth_membershipbehavior, unknown-user handling) plus method-level YARD (@param/@return, and the Puppet-version-compat rationale behindis_new_format?). Visible today viapuppet stringsHTML/JSON andpuppet describe; becomes REFERENCE.md content the moment the renderer learns providers.REFERENCE.mdcommitted as currently generated (header-only) + thevalidate:stringsjob. The job passes now and doubles as a forcing function: when a future openvox-strings starts rendering providers, validation fails and prompts a regeneration.lib/change) with CHANGELOG.An upstream PR adding a provider template to voxpupuli/openvox-strings is being prepared separately — that's the real fix for useful REFERENCE.md content here.
Verified locally: specs 8/8 (1 pending), rubocop clean,
validate:strings, RELENG checks, metadata lint.🤖 Generated with Claude Code
https://claude.ai/code/session_01XCnDsYaJDLiP8z8tafz9Tp