Adding a provider page and menu
* Add categories to html search bar
* Require provider handler and object classes
* Fetch provider code objects from registry
* Add function to generate the provider list
* Fetch providers from registry in monkey patches
* Add provider templates
* Add provider code object
* Add provider handler
* Add erb file to populate the provider list
* Don't emit type information for providers in html
* Add tests for provider handler
Refactor heredoc:
* Remove heredoc annotations
* Move heredoc functions into a heredoc helper
* Add heredoc helper class
Since we threw away all of Yard's warnings we are no longer checking that the
parameter names match for Ruby methods. Thus we need to override Yard's
method_details template with our own to trigger our warning function. However,
there's a catch. If this ruby method is in a Puppet 4x function, we don't want
our warning function to trigger because the user has already been warned. Look
in the registry to see if there is already a Puppet 4x function with the same
name registered.
Also, print errors to stderr instead of using log.warn.
Before this commit:
packages (Array[String])- A list of packages to be installed
With this commit:
packages (Array[String]) - A list of packages to be installed
Redirect Yard command line warnings to a log file called `.yardwarns`.
Yard warnings may be irrelevant, spurious, or may not conform with our
styling and UX design. They are also printed on stdout by default.
You can pass a block to the constructor of the hostclass. For some reason Yard
is yielding the block twice. Our code is not yielding the block because we only
use yield in one place which is unrelated. I don't think this is intended
behavior on yard's part, it certainly seems odd, but we can dodge the question
and not have to wait for an upstream patch by extracting the logic from the
block and running it after the object has been initialized.
I forgot to include the code which extracts the type information for the code
object in the defined types handler. Without this we do not extract type
information from defined types so warnings cannot be emitted and types in the
documentation are listed as Unknown.
Subclasses have their superclass as part of their namespace and objects in the
subclass's namespace must be registered first.
Reverse the list of parsed objects so
that the classes will be handled and registered in the correct order.
Addresses @hlindberg's comment after PR #35 was closed.
Use the error message from the exception which is actually exactly what I
wanted to say anyway.
The transformer comment matching regex matched all whitespace after a comment.
Lines which were effectively "blank" and just had a comment would be erased.
Markdown lists need to end with a blank line. This messed up markdown
formatting.
The culprit is the regex /^\s*#\s/ which matches all of the comment ' #\n',
however we want to leave the newline alone for markdown to parse.
We replace the regex with /^\s*#[ \t]/ which will only match tabs or spaces
after the hash and leave our beloved newline alone.
The previous iteration eagerly grabbed all parameters when any puppet function
was created. We did not retrieve type information and would grab parameters
from any helper functions!
* Parse the Ruby AST for dispatch blocks which specify type information. Parse
the commands and arguments in those blocks.
* If there are no dispatch blocks, parse the AST for a ruby function with the
same name as the puppet function being created.
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.
Print the name of the parameter, the file, and the line number to stderr if the
parameter name does not match the name specified in the docs.
In order for this to be useful we need to present the user with the file name
and line number of the relevant parameters. This information needs to be
extracted from the code object and passed to the extract_param_details method.
Prior to this commit, puppet namespaces would be totally mangled when
processed by YARD since YARD is looking for Ruby namespaces where the
first letter of each segment must be uppercase.
In order to fix this, patch the relevant regular expression constants
in YARD so that they will accept segments that begin with uppercase
and lowercase letters.
An upstream pull request has been accepted into YARD to add another
regex constant which is necessary to complete this patch. However until
the next version of the YARD gem is released, we must include a temporary
hack to fix the problematic method in question (as it is not yet using
the added variable). Once the new version is released, the conditional
statement in code_ext/yard.rb can be removed entirely and all we will
need to do is patch the two regex constants.
Prior to this commit, the fix for the 3x function issue was trying
to create an empty hash by calling Hash[ [[]] ] which in Ruby 1.9.3
produced and empty hash. However this is not the case in Ruby 2.0 and
up. Therefor, fix up the code so that it does not rely on Hash[ [[]] ]
creating and empty hash.
Prior to this commit, the 3x function handler assumed that at
least two arguments (the name and one or more additional arguments)
were passed into newfunction when creating a 3x function. However
that is not actually required, the only argument needed is the name.
Update the 3x function handler so that it will not throw and exception
if only one argument is given.
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.
Prior to this commit, some of the comments in the code were not as
clear as they should have been and in some places comments were not
present where they were needed. Clean up existing comments and
add some for sections of code that are not very clear.
Additionally, some sections of the template for puppet namespaces
didn't really make sense to include, especially since we want the source
of truth for documentation of 3x functions to be the :doc string which is
passed in (not the comment block above the function). Thus, remove some of
the unneeded sections from the puppet namespace template.
Prior to this commit, the @param tag was not supported for 3x
functions since we could not derive any information about the
parameter from the code itself. Since we would still like users
to be able to document parameters if they wish, update the code so
that if a parameter is documented in the 3x :doc string it will be
displayed in the HTML.
Prior to this commit some of the logic used to extract data from
comments for templates was duplicated and a little messy. Create
the TemplateHelper class so that can be simplified and cleaned up
to make things more readable and efficient.
Prior to this commit there was a lot of duplicated code around
the generation of HTML for templates. Clean up and simplify code by
adding an HTMLHelper class with helper functions which can be used
in place of repeated logic.
Prior to this commit, all the HTML for puppet functions was just
generated by YARD as if it were a regular method. Since we ultimately
want to have our own custom templates, lay out the groundwork for customizing
the templates for functions and update the page headers to be more
readable.
At the moment the code is functional but contains a lot of duplication which
needs to be cleaned up.
Prior to this commit we were not calling htmlify on the docstring
for the description of a puppet class on defined type. This meant that
the raw string would be displayed without paying attention to any
potential markdown or rdoc formatting present.
Now the YARD method htmlify is being called on the docstring so that
it will be displayed properly.
Additionally clean up an unclear comment and fix a small bug in
the way parameter information is processed.
Prior to this commit there was a header and a sub-header for
defined types and classes. This was a little redundant so rather
than doing that, remove the sub-header and make the main header
more readable.
Do a bit of renaming and add some comments to make the processing
of parameter details a bit more clear. Additionally, update the
example in the README so that it will actually be parsed properly
by YARD (since YARD does not expect the one line title before the
description).
Prior to this commit if the type for a parameter was not specified
in the comment, nothing would be printed. Since we'll soon be adding
functionality which will determine the type programmatically, it
made more since to leave a place holder rather than nothing at all.
As such, the type is now listed as "TBD" if it is not specified
by the user in the comment.
Prior to this commit there were a few issues in the way information
about parameters was collected. The previous implementation relied
on parameters and their corresponding comments to be listed in the
same order. Now the parameter is matched to the corresponding comment
using the parameter name in the comment.
Additionally, if a comment is present for a parameter that does
not actually exist in the method it will appear as strike through
in the HTML.
Prior to this commit, most of the HTML created for documenting
puppet code was auto-generated by YARD, meaning that it was not
always presented in a way that was consistent or easy to read.
Now we are explicitly defining the HTML and styling that we want
to use when generating documentation for defined types and classes.
This means that we can define exactly how we want the output to look
so that is more compatible with puppet code.
Prior to this commit, two require statements were in the wrong
order, causing strings to fail when running against anything that
required the future parser.
Now, those requires have been flipped and strings can run with
`--parser future` successfully.
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.
The plugin.rb file really only did configuration of components that were already loaded.
By relocating to the strings.rb file, it provides a central place for all of the loading
and configuration of the strings components.
Prior to this commit, the requires for the puppetx portion of this
project were dealt with in each individual file. In order to make
the code more readable and the requires more clear, move them all
into the strings file.
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.
Prior to this commit, the handlers and code objects which dealt with
puppet functions were referred to as `FutureParserFunctions` and
`ParseFunctions`. This naming convention will not make very much
sense going forward when the future parser becomes the primary
parser. Therefor, rename `FutureParserFunctions` to `Puppet4xFunctions`
and `ParserFunctions` to `Puppet3xFunctions`.
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 patch recurses into any `create_function` block and processes any
`dispactch` blocks contained within. The implementation assumes docstrings will
be provided as a comment block, but this is just a temporary placeholder.
Idealy, the contents of the `dispatch` block would be processed to produce an
`@override` tag for 4.x functions.
All Future Parser functions are documented using a standard YARD comment block.
This commit adds a new code object that watches for `create_function` and
generates a YARD `CodeObject::MethodObject` containing the docstring.
The Puppet Core uses a `.yardopts` file that hides all docstrings that do not
have an API tag. This patch is a hack that allows `puppet yardoc` to extract
documentation for parser functions shipped in the core.
FIXME: This isn't the right way to solve the problem. The right way to solve
the problem is to adjust the Puppet `.yardopts` file to a sane value.
The `namespace_list` helper is used to filter YARD objects in order to populate
search lists. The code was originally derived from the `class_list` helper.
This patch guards against calling `children` on objects that have no children
and removes a recursive call to the old `class_list` method.
This class is functionally equivalent to the ModuleObject class that YARD uses
for Ruby code. Using a new class allows us to gather YARD objects related to
Puppet and separate them from the Ruby bits.
This method has an inverted conditional which means the progress bar still
animates when `--debug` is passed. Not having an easy way to switch the
animation off is a real bummer as it completely hoses the Pry REPL.
Ref. lsegal/yard#783
This handler triggers on all occurrences of `newfunction` and parses the
parameters passed to that method in order to generate documentation. The
implementation is a good experiment in extracting documentation without
evaluating Ruby code. However, the generality of this approach may ultimately
be doomed by the use of metaprogramming in custom Types and Providers.
The default YARD template lumps anything that inherits from `NamespaceObject`
into the "Classes" list in HTML output. This patch alters the list generation
logic so that Namespaces parsed from manifests are listed in a separate
"Puppet Manifests" list.
The Future Parser will return nil if a manifest file contains no statements
(I.E. it is empty or full of comments). Handle these cases and ensure the
`enumerate` method of the YARD parser always returns an Array.
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 `YARD::Registry#resolve` method assumes all subclasses of `NamespaceObject`
respond to `inheritance_tree`.
Ref commit d6a4791 for a similar case with `HostClassObject`.
This reverts commit a051319b34.
Added a FIXME note to `defined_type_object.rb` that explains why this patch was
originally created, why it was reverted and what unresolved issues remain.
Puppet Yardoc now generates documentation for defined types in addition to host
classes. The actual change was fairly small, however this patch is quite large
as most of the host class bits were re-architected to inherit from defined
types. Host classes are basically the same as defined types with the addition
of inheritance. Pops also models Host Class using a similar inheritance
relationship.
Re-worked the YARD transformer and handlers to attach parameters to the
resulting code objects. Some architectural debt was incurred in the interests
of producing a working prototype quickly.
When creating an object, YARD will split the object name using `::` and
recursively create proxy namespaces for each component. Unfortunately this
process is optimized for Ruby and somewhat mangles Puppet code as Puppet class
names are not capitalized.
For now, dispense with this behavior by implementing `HostClassObject.new`.
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.
Instead of documenting Puppet classes using `ClassObject`, use a custom
subclass of `NamespaceObject`. This is done because Puppet classes are not Ruby
classes and will have components that don't fit into the model offered by
`ClassObject`.
This commit also adds a couple of monkey patches to integrate the new
`:hostclass` into YARD tooling and the beginnings of some custom templating.
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.
The YARD plugin is currently architected using `require_relative` so that it
can be loaded outside of Puppet. Unfortunately, `require_relative` first
appeared in Ruby 1.9.1.
Achieve compatibility using the Backports gem.
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.
Ian Kronquist