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

86 lines
4.8 KiB
Markdown
Raw Permalink 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
(PDOC-63) Implement the Puppet Strings rake tasks. This commit implements the `strings:generate` and `strings:gh_pages:update` rake tasks. The `strings:generate` task is responsible for generating Puppet Strings documentation. The `strings:gh_pages:update` task is responsible for updating the `gh_pages` branch of a GitHub repository with the latest Puppet Strings documentation.
2016-09-11 21:46:57 +00:00
==============
(maint) Rename puppetlab-strings to puppet-strings where appropriate. This commit changes the source and documentation to reference this project as `puppet-strings` rather than `puppetlabs-strings`. This makes the source and project match the gem name.
2016-08-23 19:55:40 +00:00
[![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
Add README.md
2014-05-30 19:13:30 +00:00
more fixes
2018-03-22 21:46:54 +00:00
Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby. Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
Add README.md
2014-05-30 19:13:30 +00:00
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
| | |
| -------------- |---------------------------------------------------------------- |
| *Code* | [GitHub][repo] |
| *Issues* | [Puppet JIRA Tracker][JIRA] |
| *License* | [Apache 2.0][LICENSE] |
| *Change log* | [CHANGELOG.md][changelog] |
| *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
(PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations.
2015-07-17 17:56:22 +00:00
(maint) Rename puppetlab-strings to puppet-strings where appropriate. This commit changes the source and documentation to reference this project as `puppet-strings` rather than `puppetlabs-strings`. This makes the source and project match the gem name.
2016-08-23 19:55:40 +00:00
[repo]: https://github.com/puppetlabs/puppet-strings
(PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations.
2015-07-17 17:56:22 +00:00
[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
(maint) Rename puppetlab-strings to puppet-strings where appropriate. This commit changes the source and documentation to reference this project as `puppet-strings` rather than `puppetlabs-strings`. This makes the source and project match the gem name.
2016-08-23 19:55:40 +00:00
[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
(PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations.
2015-07-17 17:56:22 +00:00
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
## Installing Puppet Strings
### Requirements
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
* Ruby 2.1.9 or newer
* Puppet 4.0 or newer
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
* The `yard` Ruby gem
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
first edit pass README
2018-03-20 00:27:23 +00:00
### Install Puppet Strings
(PDOC-80) Remove runtime dependency on puppet The runtime dependency on puppet presents problems when puppet is not installed on the system as a gem, as is the case in PE installations. Because the dependency will only be satisfied by a gem, strings currently cannot be installed in PE 3.8. This had to be worked around in newer PE versions with a fake gemspec file. Another issue is that installing strings with an older version of puppet will force an upgrade to the newest version of puppet via the gem. This commit replaces the runtime dependency on puppet with a requirement which will be present on the gem homepage on rubygems.org. Requirements are meant to list external requirements needed for the gem to work, which is correct for puppet as it can be present via a different type of package.
2016-09-28 17:14:50 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
1. Install the YARD gem by running `gem install yard`
1. Install the `puppet-strings` gem by running `gem install puppet-strings`
1. **Optional**: Set YARD options for Strings
remove duplicated docs from README, refer to docs site
2018-05-10 23:44:10 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
To use YARD options with Puppet Strings, specify a `yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
remove duplicated docs from README, refer to docs site
2018-05-10 23:44:10 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
(PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations.
2015-07-17 17:56:22 +00:00
remove duplicated docs from README, refer to docs site
2018-05-10 23:44:10 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
## Generating documentation with Puppet Strings
(PDOC-33) Inform reader how to install yard gem The easiest cross platform way to install the yard gem is actually with puppet itself. We still need to cover the puppet 3.x vs 4.x cases though.
2015-07-28 00:01:27 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead.
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
more fixes
2018-03-22 21:46:54 +00:00
Strings generates reference documentation based on the code and Strings code comments in all Puppet and Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories.
(PDOC-33) Inform reader how to install yard gem The easiest cross platform way to install the yard gem is actually with puppet itself. We still need to cover the puppet 3.x vs 4.x cases though.
2015-07-28 00:01:27 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
Strings outputs HTML of the reference information and the module README to the module's `./doc/` directory. This output can be rendered in any browser.
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
first edit pass README
2018-03-20 00:27:23 +00:00
JSON and Markdown output include the reference documentation only. Strings sends JSON output to either STDOUT or to a file. Markdown output is written to a REFERENCE.md file in the module's main directory.
(PDOC-33) Inform reader how to install yard gem Also includes a variety of other README updates and modernizations.
2015-07-17 17:56:22 +00:00
remove duplicated docs from README, refer to docs site
2018-05-10 23:44:10 +00:00
See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings. For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/5.5/puppet_strings_style.html).
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
### Additional Resources
Here are a few other good resources for getting started with documentation:
* [Module README Template](https://docs.puppet.com/puppet/latest/reference/modules_documentation.html)
* [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)
## Developing and Contributing
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
We love contributions from the community!
(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
first edit pass README
2018-03-20 00:27:23 +00:00
If you'd like to contribute to `puppet-strings`, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process.
(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-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
### Running Specs
(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-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
If you plan on developing features or fixing bugs in Puppet Strings, it is essential that you run specs before opening a pull request.
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
To run specs, run the `spec` rake task:
(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
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
## Support
(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-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
Please log tickets and issues in 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.
(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-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
There is also an active #puppet channel on the Freenode IRC network.
Add README.md
2014-05-30 19:13:30 +00:00
remove duplicated docs from README, refer to docs site
2018-05-10 23:44:10 +00:00
We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
Add README.md
2014-05-30 19:13:30 +00:00
(PDOC-133) Edits to Strings README
2016-11-23 18:49:09 +00:00
Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.