(PUP-12057) Generate resource type references #9465
Merged
Conversation
This file contains 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
bundle exec rake references:function This task uses puppet strings to generate references/function.md. The task requires the puppet-strings gems, so add it to the documentation bundler group. Since the group is optional, check to see if the gem is present before trying to load it, similar to how we handle ronn. If there are both 3.x and 4.x functions with the same name, we ignore the 3.x version and document the 4.x version. This code is adapted from puppet-docs. The old code had a bug as it used to replace /####\s/ with '###\s' resulting in a literal '\s' in the header for some functions. If `puppet-strings` gem is installed, then the man page generation will include strings as a new application type. Since we don't actually ship strings in puppet, hide it from man page generation.
bundle exec rake references:man This task generates an overview page that lists all of the puppet commands. Next, we run the gen_manpages rake task that generates roff formatted man pages in the man directory. Then we convert roff to markdown using pandoc. We unfortunately can't generate markdown directly as legacy apps are hardcoded to generate ronn, such as when running `puppet agent --help`. The task requires the pandoc-ruby gem, so add it to the documentation bundler group. Since the group is optional, check to see if the gem is present before loading it, similar to how we handle ronn. The task also requires the pandoc executable.
bundle exec references:type Run puppet strings, convert the `resource_types` and generate the type overview page in `references/types/overview.md`
This commit runs `ruby get_typedocs.rb` to extract the resource type information and render the unified page for all resource types. This code should be converted to use the puppet strings data that we're using to generate the type overview page.
This generates one page per resource type in references/types/*.md similar to what was done in puppet-docs.
Generated using `bundle exec rake references:type`
bundle exec rake references:all
joshcooper
force-pushed
the
references_types_12057
branch
from
83a6f64 to
93fc700
Compare
cthorn42
approved these changes
Sep 3, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Generates:
references/type.mdreferences/types/overview.mdreferences/types/<name>.mdOnly these commits need to be reviewed:
cc89237
3343f91
1a9c881
7df593d
93fc700
Blocked on #9464