The table_of_contents template was already too bulky and redundant and recognizing public and private components was only going to make it worse. This refactors the toc template and the toc class to use a generic outline for all components.
If there is a class, type, or function with no information documented but is pulled in by some fluke or tag we don't support, do not give it its own section
`puppet generate` behavior remains unchanged
`puppet generate --format markdown` now defaults to writing to
REFERENCE.md and will accept an override from --out
`puppet generate --format json` defaults to printing to stdout but will
accept the --out param
This implements the two remaining tags and removes the author tag. Had to do some deeper plumbing because options per function signature were not being passed along from YARD
This implements the author tag. We also claim to support the 'raise' and 'option' tags, but I don't know that we need to. This also consolidates some code in base.rb and adds docs
This makes sure the markdown doesn't include section headers that have no content. e.g. '## Classes' does not get put in if there are no classes. Also, we should deprecate --emit-json and --emit-json-stdout instead of just killing them.
This change does a few things:
1. Fixes up new api handler to return the stuff we want
2. Adds all the logic to parse YARD registries into markdown
3. Adds templates for markdown
4. Changes Face cli to use a --format option that can be used for either
markdown or json
There is a warning that displays when there is no text outside of tags for a given component, this text would become the 'Overview' section. The warning says: `[warn]: Missing documentation for Puppet class 'klass' at (stdin):4` The problem is that if the user has instead used the @summary tag, and is then using only tags, strings will report this warning even though there is clearly documentation. This adds a condition for the warning: If there is no text AND there are no tags, THEN output a warning saying there is no documentation.
When using puppet-strings with a module that otherwise does not specify rgen in its Gemfile, this error was observed:
```
$ bundle exec puppet strings generate ./manifests/*.pp
Error: The 'rgen' gem must be installed in order to use this face.
Error: Try 'puppet help strings generate' for usage
```
Adding rgen to the Gemfile allows puppet strings to work, so it seems like a valid runtime dependency.
This patch moves from using a matrix of ruby and puppet version and then
excluding the incompatibilities to including supported versions. This
makes it much easier to see what is supported while also ensuring the
correct matrix of tests.
https://docs.puppet.com/puppet/4.10/about_agent.html
In the rake task strings::generate, the arguments json and yard_args
are not applied properly. The logic uses args.key?, however args is not
a Hash but a Rake::TaskArguments (and Enumerable). There is now key?
method.
Use Rake::TaskArguments.has_key? instead.
Hunter Haugen