Merge pull request #241 from kpaulisse/kpaulisse-docs-render

Fix indent and numbering in several docs

Author: ahayworth

doc/advanced-environments.md

@@ -15,13 +15,13 @@ If you are using environment names to control the behavior of Puppet, this defau
 When you supply the command line argument `--preserve-environments` (or set `settings[:preserve_environments] = true` in your [configuration file](/doc/configuration.md)), `octocatalog-diff` will instead do the following:
 
 1. Create a temporary directory
-2. Create the following symlinks from `<temporary directory>` to the corresponding directories in the checkout of your code:
+1. Create the following symlinks from `<temporary directory>` to the corresponding directories in the checkout of your code:
 
-  - `environments`
-  - `manifests`
-  - `modules`
+    - `environments`
+    - `manifests`
+    - `modules`
 
-3. Run Puppet using an environment you specify via the command line
+1. Run Puppet using an environment you specify via the command line
 
 Note that you must have set `--preserve-environments` in order for the `--environment` and/or `--create-symlinks` options (described below) to have any effect.
 

doc/advanced-puppet-master.md

@@ -4,15 +4,15 @@
 
 Please note the following caveats:
 
-0. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously).
+1. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously).
 
-0. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you.
+1. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you.
 
-0. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use
+1. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use
 the Puppet Master v4 API you may also use a Puppet Enterprise RBAC token. The user owning the token will need the "Puppet Server Compile catalogs for remote nodes" permission.
 See the [PE RBAC Token Authorization](#pe-rbac-token-authorization) section below.
 
-0. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects.
+1. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects.
 
 ## Command line options
 

doc/configuration-puppet.md

@@ -4,33 +4,33 @@ The most common use of `octocatalog-diff` is to use `puppet` locally to compile
 
 In order to successfully use Puppet to compile catalogs:
 
-0. Puppet must be installed on the system.
+1. Puppet must be installed on the system.
 
-  It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem.
+    It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem.
 
-  By default, `octocatalog-diff` will look for the Puppet binary in several common system locations.
+    By default, `octocatalog-diff` will look for the Puppet binary in several common system locations.
 
-  For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example:
+    For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example:
 
-  ```
-  ##############################################################################################
-  # puppet_binary
-  #   This is the full path to the puppet binary on your system. If you don't specify this,
-  #   the tool will just run 'puppet' and hope to find it in your path.
-  ##############################################################################################
+    ```
+    ##############################################################################################
+    # puppet_binary
+    #   This is the full path to the puppet binary on your system. If you don't specify this,
+    #   the tool will just run 'puppet' and hope to find it in your path.
+    ##############################################################################################
 
-  # settings[:puppet_binary] = '/usr/bin/puppet'
-  settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet'
-  ```
+    # settings[:puppet_binary] = '/usr/bin/puppet'
+    settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet'
+    ```
 
-0. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled):
+1. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled):
 
-  Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package.
+    Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package.
 
-  Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem.
+    Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem.
 
-  :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states:
+    :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states:
 
-  > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure.
+    > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure.
 
-  Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation.
+    Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation.

doc/configuration.md

@@ -2,51 +2,51 @@
 
 `octocatalog-diff` may require configuration to work correctly with your Puppet setup.
 
-0. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories.
+1. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories.
 
-  - In the base directory of your Puppet repository checkout (i.e., your current working directory):
+    - In the base directory of your Puppet repository checkout (i.e., your current working directory):
 
-    ```
-    .octocatalog-diff.cfg.rb
-    ```
+      ```
+      .octocatalog-diff.cfg.rb
+      ```
 
-  - In your home directory:
+    - In your home directory:
 
-    ```
-    $HOME/.octocatalog-diff.cfg.rb
-    ```
+      ```
+      $HOME/.octocatalog-diff.cfg.rb
+      ```
 
-  - In one of the following system locations:
+    - In one of the following system locations:
 
-    ```
-    /usr/local/etc/octocatalog-diff.cfg.rb
-    /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb
-    /etc/octocatalog-diff.cfg.rb
-    ```
+      ```
+      /usr/local/etc/octocatalog-diff.cfg.rb
+      /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb
+      /etc/octocatalog-diff.cfg.rb
+      ```
 
-  Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish.
+    Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish.
 
-0. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration.
+1. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration.
 
-  To be minimally functional, you will almost certainly need to define at least the following settings:
+    To be minimally functional, you will almost certainly need to define at least the following settings:
 
-  - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file
-  - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file
-  - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained
+    - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file
+    - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file
+    - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained
 
-  For more information on these settings:
+    For more information on these settings:
 
-  - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md)
-  - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md)
-  - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md)
-  - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md)
+    - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md)
+    - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md)
+    - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md)
+    - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md)
 
-0. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof.
+1. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof.
 
-  ```
-  octocatalog-diff --config-test
-  ```
+    ```
+    octocatalog-diff --config-test
+    ```
 
-  Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed.
+    Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed.
 
 Now that you have entered your configuration and confirmed proper reading of your configuration file, proceed to [Basic usage](/doc/basic.md) to see if it works!

doc/dev/integration-tests.md

@@ -58,6 +58,6 @@ end
 
 ## Hints for writing an integration test
 
-0. If your integration test deals only with the calculation or display of differences, and not catalog compilation, and you are compiling catalogs multiple times, prefer `spec_catalog_old` and `spec_catalog_new` to pass in pre-compiled catalogs. This will make the test run faster.
+1. If your integration test deals only with the calculation or display of differences, and not catalog compilation, and you are compiling catalogs multiple times, prefer `spec_catalog_old` and `spec_catalog_new` to pass in pre-compiled catalogs. This will make the test run faster.
 
-0. It's a good idea to check the exit code in a test of its own, and then `pending` any subsequent tests if that exit code doesn't match. This way only one test, and not all the tests, will fail if the catalog compilation doesn't work.
+1. It's a good idea to check the exit code in a test of its own, and then `pending` any subsequent tests if that exit code doesn't match. This way only one test, and not all the tests, will fail if the catalog compilation doesn't work.