README.md in puppet_forge-2.2.6 vs README.md in puppet_forge-2.2.7
- old
+ new
@@ -1,11 +1,11 @@
-#Puppet Forge
+# Puppet Forge
Access and manipulate the [Puppet Forge API](https://forgeapi.puppetlabs.com)
from Ruby.
-##Installation
+## Installation
Add this line to your application's Gemfile:
gem 'puppet_forge'
@@ -15,35 +15,35 @@
Or install it yourself as:
$ gem install puppet_forge
-##Requirements
+## Requirements
* Ruby >= 1.9.3
-##Dependencies
+## Dependencies
* [Faraday]() ~> 0.9.0
* [Typhoeus](https://github.com/typhoeus/typhoeus) ~> 0.7.0 (optional)
Typhoeus will be used as the HTTP adapter if it is available, otherwise
Net::HTTP will be used. We recommend using Typhoeus for production-level
applications.
-##Usage
+## Usage
First, make sure you have imported the Puppet Forge gem into your application:
-``` ruby
+```ruby
require 'puppet_forge'
```
Next, supply a user-agent string to identify requests sent by your application
to the Puppet Forge API:
-``` ruby
+```ruby
PuppetForge.user_agent = "MyApp/1.0.0"
```
Now you can make use of the resource models defined by the gem:
@@ -74,20 +74,20 @@
The slug format, properties, associations, and methods available on each
resource model are documented on the [Resource Reference][resource_ref] page.
[resource_ref]: https://github.com/puppetlabs/forge-ruby/wiki/Resource-Reference
-###Basic Interface
+### Basic Interface
Each of the models uses ActiveRecord-like REST functionality to map over the Forge API endpoints.
Most simple ActiveRecord-style interactions function as intended.
Currently, only unauthenticated read-only actions are supported.
The methods find, where, and all immediately make one API request.
-``` ruby
+```ruby
# Find a Resource by Slug
PuppetForge::User.find('puppetlabs') # => #<Forge::V3::User(/v3/users/puppetlabs)>
# Find All Resources
PuppetForge::Module.all # See "Paginated Collections" below for important info about enumerating resource sets.
@@ -95,27 +95,27 @@
# Find Resources with Conditions
PuppetForge::Module.where(query: 'apache') # See "Paginated Collections" below for important info about enumerating resource sets.
PuppetForge::Module.where(query: 'apache').first # => #<Forge::V3::Module(/v3/modules/puppetlabs-apache)>
```
-For compatibility with older versions of the puppet_forge gem, the following two methods are functionally equivalent.
+For compatibility with older versions of the puppet\_forge gem, the following two methods are functionally equivalent.
-``` ruby
+```ruby
PuppetForge::Module.where(query: 'apache')
PuppetForge::Module.where(query: 'apache').all # This method is deprecated and not recommended
```
-####Errors
+#### Errors
All API Requests (whether via find, where, or all) will raise a Faraday::ResourceNotFound error if the request fails.
-###Installing a Release
+### Installing a Release
A release tarball can be downloaded and installed by following the steps below.
-``` ruby
+```ruby
release_slug = "puppetlabs-apache-1.6.0"
release_tarball = release_slug + ".tar.gz"
dest_dir = "/path/to/install/directory"
tmp_dir = "/path/to/tmpdir"
@@ -135,50 +135,50 @@
# @raise RuntimeError if it fails to extract the contents of the release tarball
PuppetForge::Unpacker.unpack(release_tarball, dest_dir, tmp_dir)
```
-###Paginated Collections
+### Paginated Collections
The Forge API only returns paginated collections as of v3.
-``` ruby
+```ruby
PuppetForge::Module.all.total # => 1728
PuppetForge::Module.all.length # => 20
```
Movement through the collection can be simulated using the `limit` and `offset`
parameters, but it's generally preferable to leverage the pagination links
provided by the API. For convenience, pagination links are exposed by the
library.
-``` ruby
+```ruby
PuppetForge::Module.all.offset # => 0
PuppetForge::Module.all.next_url # => "/v3/modules?limit=20&offset=20"
PuppetForge::Module.all.next.offset # => 20
```
An enumerator exists for iterating over the entire (unpaginated) collection.
Keep in mind that this will result in multiple calls to the Forge API.
-``` ruby
+```ruby
PuppetForge::Module.where(query: 'php').total # => 37
PuppetForge::Module.where(query: 'php').unpaginated # => #<Enumerator>
PuppetForge::Module.where(query: 'php').unpaginated.to_a.length # => 37
```
-###Associations & Lazy Attributes
+### Associations & Lazy Attributes
Associated models are accessible in the API by property name.
-``` ruby
+```ruby
PuppetForge::Module.find('puppetlabs-apache').owner # => #<Forge::V3::User(/v3/users/puppetlabs)>
```
Properties of associated models are then loaded lazily.
-``` ruby
+```ruby
user = PuppetForge::Module.find('puppetlabs-apache').owner
# This does not trigger a request
user.username # => "puppetlabs"
@@ -194,41 +194,41 @@
The PuppetForge gem will default to outputing all error messages in English, but you may set the locale
using the `FastGettext.set_locale` method. If translations do not exist for the language you request then the gem will
default to English. The `set_locale` method will return the locale, as a string, that FastGettext will now
use to report PuppetForge errors.
-``` ruby
+```ruby
# Assuming the German translations exist, this will set the reporting language
# to German
locale = FastGettext.set_locale "de_DE"
# If it successfully finds Germany's locale, locale will be "de_DE"
# If it fails to find any German locale, locale will be "en"
```
-##Caveats
+## Caveats
This library currently does no response caching of its own, instead opting to
re-issue every request each time. This will be changed in a later release.
-##Reporting Issues
+## Reporting Issues
Please report problems, issues, and feature requests on the public
[Puppet Labs issue tracker][issues] under the FORGE project. You will need
to create a free account to add new tickets.
[issues]: https://tickets.puppetlabs.com/browse/FORGE
-##Contributing
+## Contributing
1. Fork it ( https://github.com/[my-github-username]/forge-ruby/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
-##Contributors
+## Contributors
* Pieter van de Bruggen, Puppet Labs
* Jesse Scott, Puppet Labs
* Austin Blatt, Puppet Labs
* Adrien Thebo, Puppet Labs