(maint) Update README to reflect lack of module
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.
This commit is contained in:
Hailee Kenney
parent
2b8b4a706b
commit
b355e5d57d
109
README.md
109
README.md
|
|
@ -1,15 +1,8 @@
|
|||
**PLEASE NOTE that the puppetlabs-strings module is being deprecated in favor of a gem. 0.4.0 will be the last release of
|
||||
the puppet module and the first release of the Ruby gem. Please see the installation instructions below.**
|
||||
|
||||
Puppet Strings
|
||||
=============
|
||||
[](https://travis-ci.org/puppetlabs/puppetlabs-strings)
|
||||
[](https://travis-ci.org/puppetlabs/puppetlabs-strings) [](https://badge.fury.io/rb/puppet-strings)
|
||||
|
||||
A Puppet Face and plugin built on the
|
||||
[YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser.
|
||||
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.
|
||||
A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser. 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.
|
||||
|
||||
|
||||
| | |
|
||||
|
|
@ -33,15 +26,13 @@ In order to run strings you need to have the following software installed:
|
|||
|
||||
* Ruby 1.9.3 or newer
|
||||
* Puppet 3.7 or newer
|
||||
* The yard rubygem
|
||||
* The YARD RubyGem
|
||||
|
||||
Installing the Yard Gem
|
||||
Installing the YARD Gem
|
||||
-----------------------
|
||||
**Installing the YARD Gem with Puppet**
|
||||
|
||||
**Installing the Yard Gem with Puppet**
|
||||
|
||||
|
||||
The easiest way to install the Yard gem is with Puppet itself.
|
||||
The easiest way to install the YARD gem is with Puppet itself.
|
||||
|
||||
For Puppet 4.x:
|
||||
```
|
||||
|
|
@ -55,8 +46,9 @@ $ puppet resource package yard provider=gem
|
|||
|
||||
Installing Strings Itself
|
||||
-------------------------
|
||||
Strings can be installed using the [puppet-strings Ruby gem](https://rubygems.org/gems/puppet-strings). To ensure it
|
||||
is installed in right place, it is best to install it using Puppet.
|
||||
**PLEASE NOTE** that Strings was previously distributed via the puppetlabs-strings module. This is no longer the preferred method of installation as the module will not longer receive updates. So even though there is still a module on the Puppet Forge, please use the RubyGem.
|
||||
|
||||
Strings can be installed using the [puppet-strings RubyGem](https://rubygems.org/gems/puppet-strings). To ensure it is installed in right place, it is best to install it using Puppet.
|
||||
|
||||
For Puppet 4.x:
|
||||
```
|
||||
|
|
@ -68,28 +60,6 @@ For Puppet 3.x:
|
|||
$ puppet resource package puppet-strings provider=gem
|
||||
```
|
||||
|
||||
Versions of less than or equal to 0.4.0 may be installed as a puppet module, but **this method of distribution is
|
||||
deprecated and the module hosted on the Puppet Forge will no longer be updated after the 0.4.0 release.** The methods
|
||||
for installing the module are:
|
||||
|
||||
Strings can be installed from the [Puppet Forge][forge strings] or from source.
|
||||
|
||||
[forge strings]: https://forge.puppetlabs.com/puppetlabs/strings
|
||||
|
||||
**Installing from the Forge**
|
||||
|
||||
Simply run this command and you're off to the races:
|
||||
|
||||
```
|
||||
$ puppet module install puppetlabs-strings
|
||||
```
|
||||
|
||||
**Installing from source**
|
||||
|
||||
Simply `git clone` this repository into your `modulepath`
|
||||
(i.e. `/etc/puppet/modules`).
|
||||
|
||||
|
||||
Running Puppet Strings
|
||||
----------------------
|
||||
|
||||
|
|
@ -123,13 +93,9 @@ $ puppet strings some_manifest.pp --emit-json-stdout
|
|||
|
||||
The schema for the JSON which Strings emits is [well documented](https://github.com/puppetlabs/puppetlabs-strings/blob/master/json_dom.md).
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 server
|
||||
|
|
@ -138,21 +104,13 @@ $ puppet strings server
|
|||
Writing Compatible Documentation
|
||||
--------------------------------
|
||||
|
||||
Since the strings module is built around YARD, a few different comment formats
|
||||
can be used. YARD can work with RDoc, meaning it is backwards compatible with
|
||||
previously documented modules. Feel free to try out strings with RDoc, but we
|
||||
are planning to move to Markdown as the standard. You can configure which you
|
||||
would like YARD to use by adding a `.yardopts` file to the root of your module
|
||||
directory which specifies the desired format:
|
||||
Since the strings module is built around YARD, a few different comment formats can be used. YARD can work with RDoc, meaning it is backwards compatible with previously documented modules. Feel free to try out strings with RDoc, but we are planning to move to Markdown as the standard. You can configure which you would like YARD to use by adding a `.yardopts` file to the root of your module directory which specifies the desired format:
|
||||
|
||||
```
|
||||
--markup markdown
|
||||
```
|
||||
|
||||
While we have yet to decide exactly how documentation should work in the
|
||||
future, here are some very basic examples to get you started using the strings
|
||||
module. These are very much subject to change as we continue to work out a
|
||||
style guide.
|
||||
While we have yet to decide exactly how documentation should work in the future, here are some very basic examples to get you started using the strings module. These are very much subject to change as we continue to work out a style guide.
|
||||
|
||||
### Functions
|
||||
Here's an example of how you might document a 4x function:
|
||||
|
|
@ -197,16 +155,9 @@ class example (
|
|||
```
|
||||
|
||||
### Types and Providers
|
||||
Strings will automatically extract the `@doc` provider docstring and any `desc`
|
||||
parameter/property docstrings.
|
||||
Strings will automatically extract the `@doc` provider docstring and any `desc` parameter/property docstrings.
|
||||
|
||||
Sometimes however, Puppet types use metaprogramming to create parameters
|
||||
and methods automatically. In those cases Strings will not be able to document
|
||||
them automatically (Strings doesn't execute the code that would generate those
|
||||
parameters), so you will need to provide hints on how to document your code. To
|
||||
document a parameter which is automatically created you must use the special
|
||||
directive `@!puppet.type.param` which may take types, the parameter name,
|
||||
and a description.
|
||||
Sometimes however, Puppet types use metaprogramming to create parameters and methods automatically. In those cases Strings will not be able to document them automatically (Strings doesn't execute the code that would generate those parameters), so you will need to provide hints on how to document your code. To document a parameter which is automatically created you must use the special directive `@!puppet.type.param` which may take types, the parameter name, and a description.
|
||||
|
||||
```ruby
|
||||
# @!puppet.type.param my_parameter This parameter needs to be explicitly
|
||||
|
|
@ -242,8 +193,7 @@ Rake Tasks
|
|||
|
||||
This module is also available as a Gem and makes two rake tasks (`strings:generate` and `strings:serve`) available in `puppet-strings/rake_tasks`. To add this to your module's CI workflow, be sure to add this module to your `Gemfile`:
|
||||
|
||||
In addition to generating the usual 'doc' directory of HTML documentation, the `strings:generate` rake task will also
|
||||
drop a strings.json file containing a JSON representation of the module into the directory the rake task was run from.
|
||||
In addition to generating the usual 'doc' directory of HTML documentation, the `strings:generate` rake task will also drop a strings.json file containing a JSON representation of the module into the directory the rake task was run from.
|
||||
|
||||
```ruby
|
||||
gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppetlabs-strings.git'
|
||||
|
|
@ -258,40 +208,27 @@ require 'puppet-strings/rake_tasks'
|
|||
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.
|
||||
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
|
||||
|
||||
Support
|
||||
-----
|
||||
Please log tickets and issues at our [JIRA tracker][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.
|
||||
Please log tickets and issues at our [JIRA tracker][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.
|
||||
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.
|
||||
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.
|
||||
|
||||
Caveats
|
||||
-------
|
||||
|
||||
- Documentation blocks must immediately precede the documented code with no
|
||||
whitespace. This is because the comment extractor possesses the elegance
|
||||
and intelligence of a bag of hammers.
|
||||
- Documentation blocks must immediately precede the documented code with no whitespace. This is because the comment extractor possesses the elegance and intelligence of a bag of hammers.
|
||||
|
||||
- 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).
|
||||
- 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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue