Merge pull request #199 from puppetlabs/MODULES-9258

(MODULES-9258) Improve referencing and add summary

Author: DavidS

README.md

@@ -1,6 +1,23 @@
 # Puppet::ResourceApi [![TravisCI Build Status](https://travis-ci.org/puppetlabs/puppet-resource_api.svg?branch=master)](https://travis-ci.org/puppetlabs/puppet-resource_api) [![Appveyor Build status](https://ci.appveyor.com/api/projects/status/8o9s1ax0hs8lm5fd/branch/master?svg=true)](https://ci.appveyor.com/project/puppetlabs/puppet-resource-api/branch/master) [![codecov](https://codecov.io/gh/puppetlabs/puppet-resource_api/branch/master/graph/badge.svg)](https://codecov.io/gh/puppetlabs/puppet-resource_api)
 
-This is an implementation of the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification. Find a working example of a new-style providers in the [Palo Alto Firewall module](https://github.com/puppetlabs/puppetlabs-panos/): [base provider](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_provider.rb), [type](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/type/panos_address.rb), [actual provider with validation and xml processing](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_address/panos_address.rb), and [new unit tests](https://github.com/puppetlabs/puppetlabs-panos/blob/master/spec/unit/puppet/provider/panos_provider_spec.rb) for 100% coverage.
+This is an implementation of the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification. Find a working example of a new-style providers in the [Palo Alto Firewall module](https://github.com/puppetlabs/puppetlabs-panos/): 
+* [Base provider](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_provider.rb)
+* [Type](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/type/panos_address.rb) 
+* [Actual provider with validation and xml processing](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_address/panos_address.rb) 
+* [New unit tests](https://github.com/puppetlabs/puppetlabs-panos/blob/master/spec/unit/puppet/provider/panos_provider_spec.rb) for 100% coverage.
+
+## [Find the full Resource API documentation here](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) 
+
+## Related Documents
+
+* The [Resource API specs](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) describes details of all the capabilities of this gem.
+* The [puppetlabs-hue module](https://github.com/puppetlabs/puppetlabs-hue) is a very simple example for using the Resource API for remote resources.
+* The [meraki module](https://github.com/meraki/puppet-module) is a full example for using the Resource API for remote resources.
+* This [Introduction to Testing Puppet Modules](https://www.netways.de/index.php?id=3445#c44135) talk describes rspec usage in more detail.
+* The [RSpec docs](https://relishapp.com/rspec) provide an overview of the capabilities of rspec.
+* Read [betterspecs](http://www.betterspecs.org/) for general guidelines on what is considered good specs.
+
+
 
 ## Deployment
 
@@ -112,6 +129,8 @@ The following keys are available for defining attributes:
   * `read_only`: values for this attribute will be returned by `get()`, but `set()` is not able to change them. Values for this should never be specified in a manifest. For example, the checksum of a file, or the MAC address of a network interface.
   * `parameter`: these attributes influence how the provider behaves, and cannot be read from the target system. For example, the target file on inifile, or the credentials to access an API.
 
+Further information about types can be found in The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#resource-definition-type)
+
 ### Writing the Provider
 
 The provider is the most important part of your new resource, as it reads and enforces state. Here is the example generated by `pdk new provider`:
@@ -168,6 +187,11 @@ The `get(context)` method returns a list of hashes describing the resources that
 
 The `create`/`update`/`delete` methods get called by the `SimpleProvider` base-class to change the system as requested by the catalog. The `name` argument is the name of the resource that is being processed. `should` contains the attribute hash - in the same format as `get` returns - with the values in the catalog.
 
+Further reading can be found in the Resource API:
+* [Resource Implementation](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#resource-implementation-provider)
+* [Implmentation of simple providers](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#implementing-simple-providers)
+* [Provider Features](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#provider-features)
+
 ### Unit testing
 
 The generated unit tests in `spec/unit/puppet/provider/foo_spec.rb` get automatically evaluated with `pdk test unit`.
@@ -262,9 +286,7 @@ Do not use the following keywords when writing a schema:
 
 After the device class, transport class and transport schema have been implemented, `puppet device` will be able to use the new provider, and supply it (through the device class) with the URL specified in the [`device.conf`](https://puppet.com/docs/puppet/5.3/config_file_device.html).
 
-#### Transport/device specific providers
-
-To allow modules to deal with different backends independently, the Resource API implements a mechanism to use different API providers side by side. For a given transport/device class (see above), the Resource API will first try to load a `Puppet::Provider::TypeName::<DeviceType>` class from `lib/puppet/provider/type_name/device_type.rb`, before falling back to the regular provider at `Puppet::Provider::TypeName::TypeName`.
+* Further reading can be found in The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#transports).
 
 ### Puppet backwards compatibility
 
@@ -289,19 +311,39 @@ module Puppet::Util::NetworkDevice::Device_type
 end
 ```
 
-## Further reading
+## Summary
 
-The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) describes details of all the capabilities of this gem.
+### Getting Started
+1. Download the [Puppet Development Kit](https://puppet.com/download-puppet-development-kit).
+2. Create a [new module](https://puppet.com/docs/pdk/latest/pdk_generating_modules.html) by running `pdk new module <MODULE_NAME>`.
+3. Open `.sync.yml` and add the follwing code to to add the `puppet-resource-api` gem:
+```
+# .sync.yml
+---
+Gemfile:
+  optional:
+    ':development':
+      - gem: 'puppet-resource_api'
+spec/spec_helper.rb:
+  mock_with: ':rspec'
+```
+4. Run `pdk update` to apply the changes.
+5. Run `pdk new provider <provider_name>` to create the type and provider files.
 
-The [hue_rsapi module](https://github.com/da-ar/hue_rsapi) is a very simple example for using the Resource API for remote resources.
+### The Type, Provider and Transport
+The type is a template for the nessesary resources such as `name` and `ensure`. More attributes can be added, as well as modified to match our resources. 
 
-The [meraki module](https://github.com/meraki/puppet-module) is a full example for using the Resource API for remote resources.
+The provider reads and enforces the state. An `initialize` method can  be used for establising connection. `get(context)` can be used to et a hash list of resources on the target system.
+The `create`/`update`/`delete` methods get called by the `SimpleProvider` base-class to change the system as requested by the catalog.
+`should`contins the attriute hash with the values in the catalog.
+See full description above for examples.
 
-This [Introduction to Testing Puppet Modules](https://www.netways.de/index.php?id=3445#c44135) talk describes rspec usage in more detail.
+Remote resource support is enable thourhg the `transport` class, which manages connections and information to and form remote resources. See above for an example transport class and a fll list of keywords for the transport class.
 
-The [RSpec docs](https://relishapp.com/rspec) provide an overview of the capabilities of rspec.
+For more detailed explainations, refer to the content above, or the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification.
 
-Read [betterspecs](http://www.betterspecs.org/) for general guidelines on what is considered good specs.
+## Contributing
+We are always welcoming bug reports and pull requests on the Resource API, so that we can continue to improve it to the best of our ability. If you would like to contribute, [have a look at our GitHub](https://github.com/puppetlabs/puppet-resource_api).
 
 ## Known Issues
 
@@ -336,10 +378,6 @@ Future possibilities:
 * [Multiple Providers](https://tickets.puppetlabs.com/browse/PDK-530)
 * [Commands API](https://tickets.puppetlabs.com/browse/PDK-847)
 
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/puppetlabs/puppet-resource_api.
-
 ### Cutting a release
 
 In some cases we need to manually cut a release outside of the regular puppet