(PDOC-33) Inform reader how to install yard gem
Also includes a variety of other README updates and modernizations.
This commit is contained in:
Ian Kronquist
parent
16186ef911
commit
5a63c9832e
119
README.md
119
README.md
|
|
@ -2,11 +2,28 @@ Puppet Strings
|
|||
=============
|
||||
[](https://travis-ci.org/puppetlabs/puppetlabs-strings)
|
||||
|
||||
A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and Puppet Future Parser.
|
||||
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.
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- |------------------------------------------------------------ |
|
||||
| *Code* | [GitHub][repo] |
|
||||
| *Issues* | [Puppet Labs' JIRA Tracker][JIRA] |
|
||||
| *License* | [Apache 2.0][LICENSE] |
|
||||
| *Change log* | [CHANGELOG.md][changelog] |
|
||||
| *Contributing* | [CONTRIBUTING.md][changelog] and [COMMITTERS.md][committers]|
|
||||
|
||||
[repo]: https://github.com/puppetlabs/puppetlabs-strings
|
||||
[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
|
||||
[LICENSE]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE
|
||||
[changelog]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/CHANGELOG.md
|
||||
[contributing]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/CONTRIBUTING.md
|
||||
[committers]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/COMMITTERS.md
|
||||
|
||||
Installation
|
||||
------------
|
||||
In order to run strings you need to have the following software installed:
|
||||
|
|
@ -15,48 +32,86 @@ In order to run strings you need to have the following software installed:
|
|||
* 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](https://forge.puppetlabs.com/puppetlabs/strings) and can be installed with `puppet module install puppetlabs-strings`.
|
||||
Install the yard rubygem with the gem command:
|
||||
|
||||
```
|
||||
$ gem install yard
|
||||
```
|
||||
|
||||
You may need to prefix this command with `bundle exec` or `sudo` depending on
|
||||
your ruby environment.
|
||||
|
||||
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
|
||||
-----
|
||||
If you cloned the repository into your `modulepath` and installed the needed
|
||||
gems, you can do the following to document a module:
|
||||
----------------------
|
||||
|
||||
Once strings has been installed you can document a puppet module:
|
||||
|
||||
```
|
||||
$ cd /path/to/module
|
||||
$ puppet strings
|
||||
```
|
||||
|
||||
This processes `README` and everything in `manifests/**/*.pp`.
|
||||
This processes `README` and all puppet and ruby files under `manifests/`
|
||||
and `lib/`.
|
||||
|
||||
To document specific manifests:
|
||||
To document specific files:
|
||||
|
||||
$ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp]
|
||||
```
|
||||
$ puppet strings some_manifest.pp [another_if_you_feel_like_it.rb]
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$ 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.
|
||||
|
||||
Here's an example of how you might document a 4x function:
|
||||
|
||||
```
|
||||
# When given two numbers, returns the one that is larger.
|
||||
# You could have a several line description here if you wanted,
|
||||
# but I don't have much to say about this function.
|
||||
|
|
@ -73,9 +128,11 @@ Here's an example of how you might document a 4x function:
|
|||
num_a >= num_b ? num_a : num_b
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
And here's an example of how you might document a class:
|
||||
|
||||
```
|
||||
# This class is meant to serve as an example of how one might
|
||||
# want to document a manifest in a way that is compatible.
|
||||
# with the strings module
|
||||
|
|
@ -89,6 +146,7 @@ And here's an example of how you might document a class:
|
|||
$first_arg = $example::params::first_arg,
|
||||
$second_arg = $exampe::params::second_arg,
|
||||
) { }
|
||||
```
|
||||
|
||||
Here are a few other good resources for getting started with documentation:
|
||||
|
||||
|
|
@ -96,9 +154,6 @@ Here are a few other good resources for getting started with documentation:
|
|||
* [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
|
||||
* [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
|
||||
|
||||
License
|
||||
-----
|
||||
See [LICENSE](https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE) file.
|
||||
|
||||
Developing and Contributing
|
||||
-----
|
||||
|
|
@ -117,8 +172,7 @@ that you can run the spec tests. You should simply have to do the following:
|
|||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -134,10 +188,13 @@ a best-effort basis, until the previous major version is no longer maintained.
|
|||
Caveats
|
||||
-------
|
||||
|
||||
- At the moment, only top-level Classes and Defined Types are parsed and formatted.
|
||||
- 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 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