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.
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, several rspec tests were using `decribe "string"'
instead of `describe constant`. Update the tests to use the constant instead.
Additionally, rename the puppet function tests to reflect the renaming of the
handlers.
In order to make contributions more accessible to the community,
add COMMITTERS.md and CONTRIBUTING.md so that there are instructions
and resources for those who would like to contribute to the strings
module.
Hailee Kenney