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.
Hailee Kenney