From 2ed04c616f2e16dbb5f6bbd7334af02f7da24ef2 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Wed, 1 Oct 2014 14:28:08 -0700 Subject: [PATCH 1/3] (PDOC-10) Update README.md to be more detailed Since puppet strings will soon release a 0.1.0 version, update the README.md file to include the necessary details about the project. --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 76 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 9367728..9d60b6d 100644 --- a/README.md +++ b/README.md @@ -2,38 +2,99 @@ Puppet Strings ============= A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and Puppet Future Parser. - -**WARNING: This is very much a science experiment in progress. Things may blow up or change rapidly depending on the Temperature in Portland on a given day.** - +It is uses YARD and the Puppet Parser to generate HTML documentation about +Puppet code and Puppet extensions written in Ruby. It will eventually replace +the `puppet doc` command once feature parity has been achieved. Installation ------------ -So far, this module has been developed against Puppet 3.6.x. -It will not work with earlier versions. +In most cases, the following will need to be installed: -Currently, just `git clone` directly into the Puppet `modulepath`. -Ensure the `yard` and `rgen` gems are installed. -If running Ruby 1.8.7, ensure the `backports` gem is installed. +* A supported Ruby version. Ruby 1.9.3 and 2.0.0 are fully supported. Anything older than Ruby 1.9 is not supported. +* A supported Puppet version. Anything older than Puppet 3.6.x is not supported. +In order to install the strings module, simply `git clone` this repository into +your `modulepath` (i.e. `/etc/puppet/modules`) and ensure that you have the +`yard` and `rgen` gems installed. -Usage +Alternatively, you can clone the repository elsewhere and run the `puppet strings` +command directly from the source directory if you install the need gems via +bundler and the provided Gemfile. + +Once this module has been officially released to the Forge, you will also be +able to install it using the `puppet module install` command. + +Running Puppet Strings ----- -Documenting a module: +If you cloned the repository into your `modulepath` and installed the needed +gems, you can do the following to document a module: - cd /path/to/module - puppet strings + $ cd /path/to/module + $ puppet strings This processes `README` and everything in `manifests/**/*.pp`. Documenting specific manifests: - puppet strings some_manifest.pp [another_if_you_feel_like_it.pp] + $ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp] + +If you would like to run strings from the source directory as described above, you'll +want to install the needed gems and run via bundler: + + $ bundle install --path .bundle/gems + $ bundle exec puppet strings Processing is delegated to the `yardoc` tool so some options listed in `yard help doc` are available. However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a `.yardopts` file. +The strings face does offer two actions. In addition to generating a +directory full of HTML, you can also serve up documentation for all your +modules using the `server` action: + + $ puppet strings serever + +License +----- +See [LICENSE](https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE) file. + +Developing and Contributing +----- + +We love contributions from the community! If you'd like to contribute to the strings module, +check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppetlabs-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process. + + +Running Specs +----- + + If you're going to be doing any development with puppet strings, it's essential + that you can run the spec tests. You should simply have to do the following: + + $ bundle install --path .bundle/gems + $ bundle exec rake spec + +Support +----- +Please log tickets and issues at our [JIRA tracker](http://tickets.puppetlabs.com). The +puppet strings project can be found under [PDOC](https://tickets.puppetlabs.com/browse/PDOC) on JIRA. +A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is +available for asking questions and getting help from others. In addition there +is an active #puppet channel on Freenode. + +We use semantic version numbers for our releases, and recommend that users stay +as up-to-date as possible by upgrading to patch releases and minor releases as +they become available. + +Bugfixes and ongoing development will occur in minor releases for the current +major version. Security fixes will be backported to a previous major version on +a best-effort basis, until the previous major version is no longer maintained. + +Long-term support, including security patches and bug fixes, is available for +commercial customers. Please see the following page for more details: + +[Puppet Enterprise Support Lifecycle](http://puppetlabs.com/misc/puppet-enterprise-lifecycle) Caveats ------- @@ -43,6 +104,5 @@ Caveats - Documentation blocks must immediately precede the documented code with no whitespace. This is because the comment extractor possesses the elegance and intelligance of a bag of hammers. - - Support for Ruby 1.8.7 may disappear in the future. - - - This is a science experiment. It has a high probability of exploding catastrophically instead of doing something useful. + - This project is very much a work in progress and may very well have undiscovered bugs and pitfalls. + If you discover any of these, [please file a ticket](https://tickets.puppetlabs.com/browse/PDOC). From 4abb0d04d325e4ce9f02cf3a9bd8014a6918b896 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Wed, 1 Oct 2014 14:49:19 -0700 Subject: [PATCH 2/3] (maint) Add LICENSE file Add an Apache License for this project to be consistent with other puppetlabs modules. --- LICENSE | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..99b1924 --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ + Copyright (C) 2014 Puppet Labs Inc + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 92a3bd902c69b91bf9c9b5a904fd512cc85f9874 Mon Sep 17 00:00:00 2001 From: Andrew Parker Date: Fri, 3 Oct 2014 14:59:55 -0700 Subject: [PATCH 3/3] (PDOC-10) Try to simplify the installation 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. --- README.md | 43 ++++++++++++------------------------------- 1 file changed, 12 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 9d60b6d..adf1176 100644 --- a/README.md +++ b/README.md @@ -9,21 +9,15 @@ the `puppet doc` command once feature parity has been achieved. Installation ------------ -In most cases, the following will need to be installed: +In order to run strings you need to have the following software installed: -* A supported Ruby version. Ruby 1.9.3 and 2.0.0 are fully supported. Anything older than Ruby 1.9 is not supported. -* A supported Puppet version. Anything older than Puppet 3.6.x is not supported. + * Ruby 1.9.3 or newer + * Puppet 3.7 or newer + * The yard rubygem In order to install the strings module, simply `git clone` this repository into -your `modulepath` (i.e. `/etc/puppet/modules`) and ensure that you have the -`yard` and `rgen` gems installed. - -Alternatively, you can clone the repository elsewhere and run the `puppet strings` -command directly from the source directory if you install the need gems via -bundler and the provided Gemfile. - -Once this module has been officially released to the Forge, you will also be -able to install it using the `puppet module install` command. +your `modulepath` (i.e. `/etc/puppet/modules`). This module is also available +on the puppet forge and can be installed with `puppet module install puppetlabs-strings`. Running Puppet Strings ----- @@ -36,22 +30,15 @@ gems, you can do the following to document a module: This processes `README` and everything in `manifests/**/*.pp`. -Documenting specific manifests: +To document specific manifests: - $ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp] - -If you would like to run strings from the source directory as described above, you'll -want to install the needed gems and run via bundler: - - $ bundle install --path .bundle/gems - $ bundle exec puppet strings + $ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp] Processing is delegated to the `yardoc` tool so some options listed in `yard help doc` are available. However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a `.yardopts` file. -The strings face does offer two actions. In addition to generating a -directory full of HTML, you can also serve up documentation for all your -modules using the `server` action: +In addition to generating a directory full of HTML, you can also serve up +documentation for all your modules using the `server` action: $ puppet strings serever @@ -65,12 +52,11 @@ Developing and Contributing We love contributions from the community! If you'd like to contribute to the strings module, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppetlabs-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process. - Running Specs ----- - If you're going to be doing any development with puppet strings, it's essential - that you can run the spec tests. You should simply have to do the following: +If you're going to be doing any development with puppet strings, it's essential +that you can run the spec tests. You should simply have to do the following: $ bundle install --path .bundle/gems $ bundle exec rake spec @@ -91,11 +77,6 @@ Bugfixes and ongoing development will occur in minor releases for the current major version. Security fixes will be backported to a previous major version on a best-effort basis, until the previous major version is no longer maintained. -Long-term support, including security patches and bug fixes, is available for -commercial customers. Please see the following page for more details: - -[Puppet Enterprise Support Lifecycle](http://puppetlabs.com/misc/puppet-enterprise-lifecycle) - Caveats -------