kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
puppet-strings/README.md

90 lines
3.5 KiB
Markdown
Raw Normal View History

(PDOC-3) Rename face to strings instead of yardoc 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`.
2014-09-11 00:07:33 +00:00
Puppet Strings
Add README.md
2014-05-30 19:13:30 +00:00
=============
A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and Puppet Future Parser.
(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.
2014-10-01 21:28:08 +00:00
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.
Add README.md
2014-05-30 19:13:30 +00:00
Installation
------------
(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.
2014-10-03 21:59:55 +00:00
In order to run strings you need to have the following software installed:
(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.
2014-10-01 21:28:08 +00:00
(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.
2014-10-03 21:59:55 +00:00
* Ruby 1.9.3 or newer
* Puppet 3.7 or newer
* The yard rubygem
Require Puppet >= 3.6.0 Mostly due to breaking changes in how the `puppet module list` Face works.
2014-06-10 04:20:56 +00:00
(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.
2014-10-01 21:28:08 +00:00
In order to install the strings module, simply `git clone` this repository into
(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.
2014-10-03 21:59:55 +00:00
your `modulepath` (i.e. `/etc/puppet/modules`). This module is also available
(maint) Add forge link to README To make it easier for users to find the strings module on the forge, add a link to the module's forge page in the README.
2014-10-07 18:44:39 +00:00
on the [Puppet Forge](https://forge.puppetlabs.com/puppetlabs/strings) and can be installed with `puppet module install puppetlabs-strings`.
(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.
2014-10-01 21:28:08 +00:00
Running Puppet Strings
Add README.md
2014-05-30 19:13:30 +00:00
-----
(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.
2014-10-01 21:28:08 +00:00
If you cloned the repository into your `modulepath` and installed the needed
gems, you can do the following to document a module:
Add README.md
2014-05-30 19:13:30 +00:00
(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.
2014-10-01 21:28:08 +00:00
$ cd /path/to/module
$ puppet strings
Add README.md
2014-05-30 19:13:30 +00:00
This processes `README` and everything in `manifests/**/*.pp`.
(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.
2014-10-03 21:59:55 +00:00
To document specific manifests:
(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.
2014-10-01 21:28:08 +00:00
(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.
2014-10-03 21:59:55 +00:00
$ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp]
Add README.md
2014-05-30 19:13:30 +00:00
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.
(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.
2014-10-03 21:59:55 +00:00
In addition to generating a directory full of HTML, you can also serve up
documentation for all your modules using the `server` action:
(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.
2014-10-01 21:28:08 +00:00
$ 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
-----
(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.
2014-10-03 21:59:55 +00:00
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:
(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.
2014-10-01 21:28:08 +00:00
$ 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.
Add README.md
2014-05-30 19:13:30 +00:00
Caveats
-------
- At the moment, only top-level Classes and Defined Types are parsed and formatted.
- 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.
(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.
2014-10-01 21:28:08 +00:00
- 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).