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