(PUP-12058) Add task to generate man (as markdown) reference #9464
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.
joshcooper
force-pushed
the
references_man_12058
branch
from
b2115bb to
76a4570
Compare
joshcooper
commented
Sep 2, 2024
| # https://github.com/puppetlabs/puppet-docs/blob/1a13be3fc6981baa8a96ff832ab090abc986830e/lib/puppet_references/puppet/man.rb#L119-L128 | ||
| files = Pathname.glob(File.join(__dir__, '../man/man8/*.8')) | ||
| files.each do |f| | ||
| next if File.basename(f) == "puppet.8" |
There was a problem hiding this comment.
Not sure we should skip this now that it's rendered correctly
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.
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.
Only this commit needs to be reviewed:
76a4570
Depends on #9463