`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 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
This commit deletes the old implementation to assist in cleaner code reviews of
the upcoming reimplementation.
This commit also moves YARD to version 0.9.5 and lays down a bare bones
implementation of Puppet Strings that currently does nothing.
This commit changes the source and documentation to reference this project as
`puppet-strings` rather than `puppetlabs-strings`.
This makes the source and project match the gem name.
* Dunno, I just plowed through a bunch of features
* Expect puppet provider in stats output
* Fetch default values for Type params and props
* Detect allowed values
* Add allowed values to test
* htmlify scrubbed text
* Add features to Type html output
* Add infrastructure for types
* Add methods for generating lists, etc.
* Add provider code object
* Add provider handler
* Generate list for puppet provider dropdown
* Add puppet provider template
* Add provider details to puppet type template
* Get description properly for types
Traverse the ruby AST to get method arguments and attach them to the code
object.
* Fixes spurious warnings issued by yard.
* Obviates the need for ugly regex code in the templates to retrieve
parameters from the source code.
Due to the changes in PUP-3900 which renamed Puppetx to PuppetX
and puppetx to puppet_x, strings was failing since the namespace
had not been updated in strings. In order to be compatible with this
change, update strings by renaming the namespace to match.
In order to ensure strings is still compatible with earlier versions
of puppet that don't include the namespace change, declare our own
PuppetX module. This way, if it is an older version and the namespace
is called Puppetx, the necessary PuppetX namespace will be created.
Due to a merge conflict that was not properly resolved, a method
which did not exist was being called in the server action, causing
the action to fail. Remove the unneeded method call so that the
server action will work as intended.
Prior to this commit, many of the classes in this project were declared
in two lines. The first line would put them in the context of the module
they belonged to, and the second line would declare the class and deal with
inheritance. In order to make the code more readable and to allow
require statements to be moved to the top level, turn all class declarations
into one line statements.
Prior to this commit, the puppet strings project was using require_relative
to include other classes and modules. Due to some ambiguity and the fact
that the strings project shares some naming conventions with YARD, the
use of require_relative sometimes made it unclear what was being
included and where it was coming from. Now require is being used and although
this requires the full path, it makes it very clear where things are coming
from.
Refactor the actions module so that it is a class. This is important
because it allows us to keep `Puppet[]` calls out of the library and
have them in the face itself. Additionally, move a few things around
(like `check_required_features` since it makes require statements
cleaner) and clean up some comments.
Refactor the code in the strings face and extract much of the functionality
into a separate library in order to make the code more readable and
sustainable. Additionally, remove the `modules` action from the face
since it does not have a clear use case currently. However since the `server`
action depends on it, and it may be helpful to add other features in the future,
extract the functionality previously contained in `modules` into a helper
method.
Since we don't want the name of the tool to reflect the fact that
it is using yard internally (this is an implementation detail), rename
the face to `strings`. Now when one wishes to generate documentation,
`puppet strings` will be used rather than `puppet yardoc`.
Add spec tests for Puppet face component, mainly around error checking.
Due to the use of `puppet module list`, the behavior of the `modules`
and `server` actions are not very feasible to test via spec testing.
Additionally, make a few minor changes to the gem file, and make a
small change in `check_required_features` to reflect the fact that
this module will no longer support anything earlier than Ruby 1.9.
This commit adds the `puppet yardoc server` action which is designed to
mimic `yard server --gems`. This action generates YARD indicies by invoking
`puppet yardoc modules` and then configures `YARD::CLI::Server` to serve the
resulting documentation.
This commit adds the `puppet yardoc modules` action which is designed to
process Puppet Modules in the same way `yard gems` processes Ruby Gems. This
action walks the list of modules generated by `puppet module list` and
generates a YARD index (.yardoc directory) in each module root. This index
contains all the data required to generate documentation using other YARD
tools.
The `puppet yardoc` command now consumes an optional list of manifest files to
document. If no files are passed, a default glob of `manifests/**/*.pp` will be
used.
Loading `Puppetx::Yardoc::YARD::Plugin` registers the subsystems for Puppet
documentation with YARD. At this point, execution can be handed off to the
`YARD::CLI::Yardoc` tool.
Use `require_relative` for all components under Puppetx. This makes it possible
to load `pupetx/yardoc/yard/plugin` outside of Puppet as a YARD plugin.
Also fix the `yardoc` face so that Puppetx bits are loaded _after_ feature
checks.
The `YARDStatement` class is an adaptor that composes a `Pops::Model` instance
along with applicable `Pops::Adapter` and presents a familiar interface for
`YARD::Handler` objects to work with.
Start building a YARD parser. Parsing and comment extraction has been moved out
of the yardoc face and into the new `Puppetx::Yardoc::YARD::PuppetParser`
class. The old `Commentor` class from the Util module has been renamed to
`Puppetx::Yardoc::Pops::YARDTransformer`.
`puppet yardoc` is still capable of extracting docstrings for node, class and
type definitions from a single manifest file.
Ewoud Kohl van Wijngaarden