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.
Running `puppet strings server` generates documentation for all
modules in your modulepath, meaning that it also generates HTML
for strings itself. Since there are parts of strings that are not
meant to be documented with YARD, exclude the files that cause
error messages so that `puppet strings server` is not needlessly
noisy.
Additionally, make a few suggested changes to the README to make
it clearer and easier to read.
In order to make it easier for users, give some basic examples
in the README of how write documentation that is compatible with
strings. Also provide a few resources for getting started.
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.
In order to ensure long term code quality, add a rubocop check to
the travis job which runs when a pull request is submitted. Do this
by adding a rake task for rubocop and setting up travis to run
both the spec rake task and the rubocop one.
Additionally, make a few changes to the .rubocop.yml file so it
will stop complaining about incorrect namespaces.
Since we want to use rubocop to help maintain the code quality of
this project, add a .rubocop.yml file (borrowed from the puppet repo)
so that we can successfully enforce the things we want and disable
those we don't.
In the previous commit, the metadata.json file was changed to have
puppet as a dependency rather than a requirement. This caused the
module to try to install puppet from the Forge which was not the
desired behavior for many reasons. Therefor, update the metadata
file to use requirements instead of dependencies.
In order to allow for multiple platforms on Jenkins, use the
platform environment variable in the rake task for acceptance tests
to determine which platform to run on.
Prior to this commit, the test module used in testing was using
a Modulefile rather than metadata.json. Switch to metadata.json
instead since Modulefile is deprecated and was causing a deprecation
warning during acceptance testing.
In order to help ensure that the strings module is not broken
during development, add a full system integration test which can
run at regular intervals to ensure that the module is working as
expected.
The test installs the string module as well as a test module which
contains the different types of puppet and ruby code that the strings
module can document. It then runs strings and ensures that the HTML
generated is correct.
Additionally, make some changes to the Gemfile to allow strings to
be run as a gem even if it isn't installed in the modulepath. Also
make a few changes to the unit tests to make them compatible with
the version of rspec required by Beaker.
* hkenney-maint/master/add_committers_and_contributing_md:
(maint) Remove reference to other platforms
(maint) Remove references to stable in COMMITTERS
(maint) Add COMMITTERS.md and CONTRIBUTING.md
Closes GH-11
The "other platforms" is language from puppet where we don't always have
access to various OS and version combinations. Strings is much simpler
and so it isn't really relevant.
* hkenney-maint/master/pdoc-10_update_readme_md:
(PDOC-10) Try to simplify the installation
(maint) Add LICENSE file
(PDOC-10) Update README.md to be more detailed
The instructions for installation provided a lot of different
alternatives. In order to quickly answer the question of "how do I use
this" we can just give the most common ways of getting it installed.
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.
Since puppet strings is a very small project, at the moment we
don't need to maintain a master and a stable branch. As a result,
the COMMITTERS.md guide should not contain references to the stable
branch or include information around dealing with both the master
and stable branch. Remove these references so that COMMITTERS is
consistent with our approach to the strings repository.
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.
Hailee Kenney