From 5a63c9832e47d3afd18b51fe4e9b441fccbdc272 Mon Sep 17 00:00:00 2001 From: Ian Kronquist Date: Fri, 17 Jul 2015 10:56:22 -0700 Subject: [PATCH] (PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations. --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 88 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 1f53e20..efc918d 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,28 @@ Puppet Strings ============= [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-strings.png?branch=master)](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).