Merge branch 'hkenney-maint/master/pdoc-10_update_readme_md'
* 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
This commit is contained in:
Andrew Parker
commit
bf24ae2092
|
|
@ -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.
|
||||
75
README.md
75
README.md
|
|
@ -2,38 +2,80 @@ 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 order to run strings you need to have the following software 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.
|
||||
* 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`). This module is also available
|
||||
on the puppet forge and can be installed with `puppet module install puppetlabs-strings`.
|
||||
|
||||
Usage
|
||||
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:
|
||||
To document 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]
|
||||
|
||||
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:
|
||||
|
||||
$ 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.
|
||||
|
||||
Caveats
|
||||
-------
|
||||
|
|
@ -43,6 +85,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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue