The runtime dependency on puppet presents problems when
puppet is not installed on the system as a gem, as is the
case in PE installations. Because the dependency will only be
satisfied by a gem, strings currently cannot be installed in
PE 3.8. This had to be worked around in newer PE versions with
a fake gemspec file.
Another issue is that installing strings with an older
version of puppet will force an upgrade to the newest version of
puppet via the gem.
This commit replaces the runtime dependency on puppet with a
requirement which will be present on the gem homepage on
rubygems.org. Requirements are meant to list external requirements
needed for the gem to work, which is correct for puppet as it can be
present via a different type of package.
This commit implements the `strings:generate` and `strings:gh_pages:update`
rake tasks.
The `strings:generate` task is responsible for generating Puppet Strings
documentation.
The `strings:gh_pages:update` task is responsible for updating the `gh_pages`
branch of a GitHub repository with the latest Puppet Strings documentation.
This commit deletes the old implementation to assist in cleaner code reviews of
the upcoming reimplementation.
This commit also moves YARD to version 0.9.5 and lays down a bare bones
implementation of Puppet Strings that currently does nothing.
This commit changes the source and documentation to reference this project as
`puppet-strings` rather than `puppetlabs-strings`.
This makes the source and project match the gem name.
Update the README to reflect the fact that strings will not longer
be released as a forge module. Include a quick note to explain that
while the module is still available on the forge, that is not the
preferred method of installation because it will not be updated.
Prior to this commit, the rake task section of the README did not
reflect that strings:generate rake task would also create a strings.json
file. Update the README to include this detail.
Since 0.4.0 will be the last version of strings released as a puppet
module, update the README to reflect the fact that this method of
distribution is deprecated and add a description of how to install
the Ruby gem version of strings.
- Clarify how desc/doc strings are automatically extracted
- Clarify in the example where my_parameter comes from
- add subheadings to Writing Compatible Documentation
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).
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.
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.
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`.
Will Hopper