Fixes formatting on aws/azure resources

Signed-off-by: kagarmoe <kgarmoe@chef.io>

docs/resources/audit_policy.md.erb

@@ -4,7 +4,7 @@ title: About the audit_policy Resource
 
 # audit_policy
 
-Use the `audit_policy` Inspec audit resource to test auditing policies on the Windows platform. An auditing policy is a category of security-related events to be audited. Auditing is disabled by default and may be enabled for categories like account management, logon events, policy changes, process tracking, privilege use, system events, or object access. For each enabled auditing category property, the auditing level may be set to `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`.
+Use the `audit_policy` InSpec audit resource to test auditing policies on the Windows platform. An auditing policy is a category of security-related events to be audited. Auditing is disabled by default and may be enabled for categories like account management, logon events, policy changes, process tracking, privilege use, system events, or object access. For each enabled auditing category property, the auditing level may be set to `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`.
 
 <br>
 

docs/resources/aws_iam_policy.md.erb

@@ -3,7 +3,7 @@ title: About the aws_iam_policy Resource
 platform: aws
 ---
 
-# aws_iam_policy
+# aws\_iam\_policy
 
 Use the `aws_iam_policy` InSpec audit resource to test properties of a single managed AWS IAM Policy.
 

docs/resources/aws_iam_role.md.erb

@@ -48,6 +48,8 @@ A textual description of the IAM Role.
 
 ## Matchers
 
+This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
 ### exist
 
 Indicates that the Role Name provided was found. Use should_not to test for IAM Roles that should not exist.

docs/resources/aws_kms_keys.md.erb

@@ -71,7 +71,7 @@ Provides a list of key ids for all KMS Keys in the AWS account.
 
 ## Matchers
 
-For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### exists
 

docs/resources/aws_s3_bucket.md.erb

@@ -109,6 +109,8 @@ If there is no bucket policy, this property returns an empty array.
       s.effect == 'Allow' && s.principal == '*'
     end
 
+<br>
+
 ## Matchers
 
 This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).

docs/resources/aws_security_group.md.erb

@@ -83,27 +83,23 @@ A string identifying the VPC that contains the security group. Since VPCs common
     end
 
 <br>
-
-## Matchers
-
-This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
-
-### exists
-
-The control will pass if the specified SG was found.  Use should_not if you want to verify that the specified SG does not exist.
-
-    # You will always have at least one SG, the VPC default SG
-    describe aws_security_group(group_name: 'default')
-      it { should exist }
-    end   
-
-    # Make sure we don't have any security groups with the name 'nogood'
-    describe aws_security_group(group_name: 'nogood')
-      it { should_not exist }
-    end 
-
 ## Properties
 
+* `description`, `group_id', `group_name`, `vpc_id`
+
+<br>
+
+## Property Examples
+
+### description
+
+A String reflecting the human-meaningful description that was given to the SG at creation time.
+
+    # Require a description of a particular group
+    describe aws_security_group('sg-12345678') do
+      its('description') { should_not be_empty }
+    end
+
 ### group\_id
 
 Provides the Security Group ID.
@@ -125,15 +121,6 @@ A String reflecting the name that was given to the SG at creation time.
       its('group_name') { should cmp 'my_group' }
     end
 
-### description
-
-A String reflecting the human-meaningful description that was given to the SG at creation time.
-
-    # Require a description of a particular group
-    describe aws_security_group('sg-12345678') do
-      its('description') { should_not be_empty }
-    end
-
 ### vpc\_id
 
 A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VPC that contains the security group.
@@ -142,3 +129,24 @@ A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VP
     describe aws_security_group('sg-12345678') do
       its('vpc_id') { should cmp 'vpc-12345678' }
     end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exists
+
+The control will pass if the specified SG was found.  Use should_not if you want to verify that the specified SG does not exist.
+
+    # You will always have at least one SG, the VPC default SG
+    describe aws_security_group(group_name: 'default')
+      it { should exist }
+    end   
+
+    # Make sure we don't have any security groups with the name 'nogood'
+    describe aws_security_group(group_name: 'nogood')
+      it { should_not exist }
+    end 
+

docs/resources/aws_security_groups.md.erb

@@ -50,10 +50,16 @@ A string identifying a group. Since groups are contained in VPCs, group names ar
       it { should exist }
     end
 
+<br>
+
 ## Properties
 
 * `entries`, `group\_ids`
 
+<br>
+
+## Property Examples
+
 ### entries
 
 Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations.
@@ -73,7 +79,7 @@ Provides a list of all security group IDs matched.
 
 ## Matchers
 
-For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### exists
 

docs/resources/aws_vpcs.md.erb

@@ -36,7 +36,7 @@ As this is the initial release of `aws_vpcs`, its limited functionality preclude
 
 ## Matchers
 
-For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+This InSpec audit resource has the following special matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### exists
 

docs/resources/azure_generic_resource.md.erb

@@ -4,7 +4,7 @@ title: About the azure_generic_resource Resource
 
 # azure\_generic\_resource
 
-Use the `azure_generic_resource` Inspec audit resource to test any valid Azure Resource. This is very useful if you need to test something that we do not yet have a specific Inspec resource for.
+Use the `azure_generic_resource` InSpec audit resource to test any valid Azure Resource. This is very useful if you need to test something that we do not yet have a specific Inspec resource for.
 
 ## Syntax
 
@@ -16,20 +16,19 @@ Use the `azure_generic_resource` Inspec audit resource to test any valid Azure R
 
 where
 
-* Resource Parameters
+* `MyResourceGroup` is the name of the resource group that contains the Azure Resource to be validated
-  * `MyResourceGroup` is the name of the resource group that contains the Azure Resource to be validated
+* `MyResource` is the name of the resource that needs to be checked
-  * `MyResource` is the name of the resource that needs to be checked
 * `property` - This generic resource dynamically creates the properties on the fly based on the type of resource that has been targetted.
 * `value` is the expected output from the chosen property
 
 The options that can be passed to the resource are as follows.
 
-| Name        | Description                                                                                                         | Required | Example                           |
+The options that can be passed to the resource are as follows.
-|-------------|---------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------|
+
-| group_name: | Azure Resource Group to be tested                                                                                   | yes      | MyResourceGroup                   |
+* `group_name`, the Azure resource group to be tested. Example: 'MyResourceGroup' (required)
-| name:       | Name of the Azure resource to test                                                                                  | no       | MyVM                              |
+* `name`, the name of the Azure resource to test. Example: 'MyVM'
-| type: | Azure Resource Type to look for | no | Microsoft.Compute/virtualMachines |
+* `type`, the Azure resource type. Example: 'Microsoft.Compute/virtualMachines'
-| apiversion: | API Version to use when interrogating the resource. If not set then the latest version for the resoure type is used | no       | 2017-10-9                         |
+* `apiversion`, the API Version to use when querying the resource. Defaults to the latest version for the resoure type is used. Example: 2017-10-9 
 
 These options can also be set using the environment variables:
 
@@ -42,18 +41,17 @@ When the options have been set as well as the environment variables, the environ
 
 There are _normally_ three standard tests that can be performed on a resource.
 
-| Name | Description |
+* `name`: tests the resource name
-|------|-------------|
+* `type`: tests the resource type
-| name | Name of the resource |
+* `location`: tests the resource's location within Azure
-| type | Type of resource |
-| location | Location of the resource within Azure |
 
-For example:
+## Example
 
-```ruby
+    ```ruby
-describe azure_generic_resource(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM') do
+    describe azure_generic_resource(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM') do
       its('location') { should eq 'westeurope' }
-end
+    end
+    ```
 ```
 
 ## Properties
@@ -77,3 +75,7 @@ Please see the integration tests for in depth examples of how this resource can
  - [Generic Windows Internal VM NIC](../test/integration/verify/controls/generic_windows_internal_vm_nic.rb)
  - [Generic Windows Internal VM](../test/integration/verify/controls/generic_windows_internal_vm.rb)
 
+ ## Matchers
+
+For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+ 

docs/resources/azure_resource_group.md.erb

@@ -10,11 +10,11 @@ Use the `azure_resource_group_resource_counts` InSpec audit resource to check th
 
 The name of the resource group is specified as a parameter on the resource:
 
-```ruby
+    ```ruby
-describe azure_resource_group(name: 'MyResourceGroup') do
+    describe azure_resource_group(name: 'MyResourceGroup') do
     its('property') { should eq 'value' }
-end
+    end
-```
+    ```
 
 where
 
@@ -25,10 +25,51 @@ where
 
 The options that can be passed to the resource are as follows.
 
-| Name        | Description                                                                                                         | Required | Example                           |
+## Examples
-|-------------|---------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------|
+
-| group_name: | Azure Resource Group to be tested                                                                                   | yes      | MyResourceGroup                   |
+The following examples show how to use this InSpec audit resource
-| name:       | Name of the Azure resource to test                                                                                  | no       | MyVM                              |
+
+Please refer the integration tests for more in depth examples:
+
+ - [Resource Group](../../test/integration/verify/controls/resource_group.rb)
+
+### Test Resource Group has the correct number of resources
+
+    ```ruby
+    describe azure_resource_group_resource_counts(name: 'Inspec-Azure') do
+      its('total') { should eq 7}
+    ```
+
+### Ensure that the Resource Group contains the correct resources
+
+    ```ruby
+    describe azure_resource_group_resource_counts(name: 'Inspec-Azure') do
+      its('total') { should eq 7 }
+      its('vm_count') { should eq 2 }
+      its('nic_count') { should eq 2 }
+      its('public_ip_count') { should eq 1 }
+      its('sa_count') { should eq 1 }
+      its('vnet_count') { should eq 1 }
+    end
+    ```
+
+<br>
+
+## Resource Parameters
+
+The options that can be passed to the resource are as follows.
+
+### `group_name` (required)
+
+Use this parameter to define the Azure Resource Group to be tested. 
+
+example: MyResourceGroup
+
+### name
+
+Use this parameter to define the name of the Azure resource to test
+
+example:  MyVM
 
 If both `group_name` and `name` is set then `name` will take priority
 
@@ -39,7 +80,7 @@ These options can also be set using the environment variables:
 
 When the options have been set as well as the environment variables, the environment variables take priority.
 
-For example:
+### Parameter Example
 
     ```ruby
     describe azure_resource_group_resource_counts(name: 'ChefAutomate') do
@@ -49,96 +90,172 @@ For example:
     end
     ```
 
+<br>
 
 ## Properties
 
 * `name`, `location` ,`id`, `provisioning_state`, `subscription_id`, `total`, `nic_count`, `vm_count`, `extension_count`, `vnet_count`, `sa_count`, `public_ip_count`,`managed_disk_image_count`, `managed_disk_count`, `tag_count`
 
-
 <br>
 
 ## Property Examples
 
+This InSpec audit resource has the following properties:
+
 ### name
 
 Returns the name of the resource group.
 
+    ```ruby
+    its(name) { should cmp 'nugget' }
+    ```
+
 ### location
 
 Returns where in Azure the resource group is located.
 
+    ```ruby
+    its(location) { should cmp 'us-west' }
+    ```
+
 ### id
 
 Returns the full qualified ID of the resource group.
 
 This is in the format `/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>`.
 
-### provisioning\_state
+    ```ruby
+    its(id) { should cmp 'FQDN' }
+    ```
+
+### provisioning_state
 
 The provisioning state of the resource group.
 
-### subscription\_id
+    ```ruby
+    its(provisioning_state) { should cmp '????' }
+    ```
+
+### subscription_id
 
 Returns the subscription ID which contains the resource group.
 
 This is derived from the `id`.
 
+    ```ruby
+    its(subscription_id) { should cmp '????' }
+    ```
+
 ### total
 
 The total number of resources in the resource group
 
-### nic\_count
+    ```ruby
+    its(total) { should eq 5 }
+    ```
+
+### nic_count
 
 The number of network interface cards in the resource group
 
-### vm\_count
+    ```ruby
+    its(nic_count) { should eq 2 }
+    ```
+
+### vm_count
 
 The number of virtual machines in the resource group
 
-### vnet\_count
+    ```ruby
+    its(vm_count) { should eq 5 }
+    ```
+
+### vnet_count
 
 The number of virtual networks in the resource group
 
-### sa\_count
+    ```ruby
+    its(vnet_count) { should eq 5 }
+    ```
+
+### sa_count
 
 The number of storage accounts in the resource group
 
-### public\_ip\_count
+    ```ruby
+    its(sa_count) { should eq 5 }
+    ```
+
+### public_ip_count
 
 The number of Public IP Addresses in the resource group
 
-### managed\_disk\_image\_count
+    ```ruby
+    its(public_ip_count) { should eq 5 }
+    ```
+
+### managed_disk_image_count
 
 The number of managed disk images that are in the resource group.
 
 These are the items from which managed disks are created which are attached to machines. Generally the images are created from a base image or a custom image (e.g. Packer)
 
-### managed\_disk\_count
+    ```ruby
+    its(managed_disk_image_count) { should eq 5 }
+    ```
+
+### managed_disk_count
 
 The number of managed disks in the resource group.
 
 If a resource group contains one virtual machine with an OS disk and 2 data disks that are all Managed Disks, then the count would be 3.
 
-<br>
+    ```ruby
+    its(managed_disk_count) { should eq 3 }
+    ```
 
+<br>
 
 ## Matchers
 
 This resource has a number of `have_xxxx` matchers that provide a simple way to test of a specific Azure Resoure Type exists in the resource group. 
 
-The following table shows the methods that are currently supported and what their associated Azure Resource Type is.
+### `have_nics`
 
-| Matcher Name | Azure Resource Type |
+Use this resource to test `
-|-------------|---------------------|
+Microsoft.Network/networkInterfaces`
-| have_nics | Microsoft.Network/networkInterfaces |
+
-| have_vms | Microsoft.Compute/virtualMachines |
+### `have_vms`
-| have_extensions | Microsoft.Compute/virtualMachines/extensions |
+
-| have_nsgs | Microsoft.Network/networkSecurityGroups |
+Use this resource to test `Microsoft.Compute/virtualMachines`
-| have_vnets | Microsoft.Network/virtualNetworks |
+
-| have_managed_disks | Microsoft.Compute/disks |
+### `have_extensions`
-| have_managed_disk_images | Microsoft.Compute/images |
+
-| have_sas | Microsoft.Storage/storageAccounts |
+Use this resource to test `Microsoft.Compute/virtualMachines/extensions``
-| have_public_ips | Microsoft.Network/publicIPAddresses |
+
+### `have_nsgs`
+
+Use this resource to test `Microsoft.Network/networkSecurityGroups`
+
+### `have_vnets` 
+
+Use this resource to test `Microsoft.Network/virtualNetworks`
+
+### `have_managed_disks`
+
+Use this resource to test `Microsoft.Compute/disks`
+
+### `have_managed_disk_images`
+
+Use this resource to test `Microsoft.Compute/images`
+
+### `have_sas`
+
+Use this resource to test `Microsoft.Storage/storageAccounts`
+
+### `have_public_ips`
+
+Use this resource to test `Microsoft.Network/publicIPAddresses`
 
 With these methods the following tests are possible
 
@@ -146,8 +263,6 @@ With these methods the following tests are possible
     it { should have_nics }
     it { should_not have_extensions }
     ```
-
-
 ## Tags
 
 It is possible to test the tags that have been assigned to the resource. There are a number of properties that can be called to check that it has tags, that it has the correct number and that the correct ones are assigned.
@@ -190,7 +305,7 @@ Then a property is available called `Owner_tag`.
 
     ```ruby
     its('Owner_tag') { should cmp 'Russell Seymour' }
-```
+    ```
 
 Note: The tag name is case sensitive which makes the test case sensitive. E.g. `owner_tag` does not equal `Owner_tag`.
 

docs/resources/windows_task.md.erb

@@ -4,7 +4,7 @@ title: About the windows_task Resource
 
 # windows_task
 
-Use the `windows_task` Inspec audit resource to test a scheduled tasks configuration on a Windows platform.
+Use the `windows_task` InSpec audit resource to test a scheduled tasks configuration on a Windows platform.
 Microsoft and application vendors use scheduled tasks to perform a variety of system maintaince tasks but system administrators can schedule their own.
 
 <br>