Make Pegleg documentation more user friendly

-Added small changes to make new users more easily understand
how to use Pegleg.
-Fixed some linking.

Change-Id: I00a8dff1f28db14f3ffd5ee04549eb57d8f1320a

docs/source/authoring_strategy.rst

@@ -18,18 +18,17 @@ Document Fundamentals
 =====================
 
 The definition of a site consists of a set of small YAML documents that
-are managed by _Deckhand http://deckhand.readthedocs.io/en/latest/. Each
+are managed by Deckhand_. Each document is identified by a ``schema`` top-level
-document is identified by a ``schema`` top-level key and the ``metadata.name``
+key and the ``metadata.name`` value that uniquely identifies a particular
-value that uniquely identifies a particular document of the type ``schema``.
+document of the type ``schema``. Deckhand provides functionality allowing
-Deckhand provides functionality allowing documents to be authored such that
+documents to be authored such that data from multiple documents can be merged.
-data from multiple documents can be merged.
 
     * Abstact vs Concrete - Documents define a value in ``metadata.layeringDefinition.abstract`` to
       determine if a document is abstract (a value of ``true``) or concrete (a value of ``false``).
       When calling the ``/revisions/{id}/rendered-documents`` API, only concrete documents are returned.
-    * Layering - Document _layering http://deckhand.readthedocs.io/en/latest/layering.html is used
+    * Layering - Document layering_ is used
       for whole documents that have known defaults but may need to be transformed in specific instances.
-    * Substitution - Data _substitution http://deckhand.readthedocs.io/en/latest/substitution.html is
+    * Substitution - Data substitution_ is
       used for extracting particular values from a document's data section (whole or in-part) and
       inserting that data into a destination document (at the root of the data section or deeper
       into a document).
@@ -40,9 +39,8 @@ Shared Documents
 Secrets
 -------
 
-Several generic document
+Several generic document types_ exist to support storing sensitive data
-_types http://deckhand.readthedocs.io/en/latest/document_types.html#provided-utility-document-kinds
+encrypted.
-exist to support storing sensitive data encrypted.
 
 These must be utilized for all data considered sensitive.
 
@@ -84,6 +82,10 @@ This catalogue pattern can also be utilized for the ``type`` layer
 if needed.
 
 .. _Deckhand: https://deckhand.readthedocs.io
+.. _layering: http://deckhand.readthedocs.io/en/latest/layering.html
+.. _substitution: http://deckhand.readthedocs.io/en/latest/substitution.html
+.. _types: http://deckhand.readthedocs.io/en/latest/document_types.html#provided-utility-document-kinds
+
 
 Global Layer
 ------------

docs/source/cli.rst

@@ -27,11 +27,19 @@ called pegleg.sh.
     the site definition libraries. Pegleg makes no assumptions about the root
     directory. $WORKSPACE is /workspace in the container context.
 
+        Example: $WORKSPACE=/home/ubuntu/all_repos
+
     $IMAGE = Location of pegleg docker image.
 
+        Example: $IMAGE=quay.io/attcomdev/pegleg:latest
+
 To run:
 
-./pegleg.sh <command> <options>
+.. code-block:: console
+
+    export WORKSPACE=<repo_location>
+    export IMAGE=<docker_image>
+    ./pegleg.sh <command> <options>
 
 
 CLI Options
@@ -43,7 +51,7 @@ Enable debug logging.
 
 Site
 ----
-Commands related to sites.
+This allows you to set the primary and auxiliary repositories.
 
 **-p / --primary**
 
@@ -64,8 +72,8 @@ Path to the root of an auxiliary repo.
 
 Collect
 -------
-Output complete config for one site. It is assumed that all lint errors have
+Output complete config for one site.
-been corrected already.
+It is assumed that all lint errors have been corrected already.
 
 **site_name**
 
@@ -137,7 +145,8 @@ Where to output.
 
 Lint
 ----
-Sanity checks for repository content.
+Sanity checks for repository content. Validations for linting are done
+utilizing `Deckhand Validations`_.
 
 ::
 
@@ -187,3 +196,6 @@ Will warn of lint failures from the specified lint options.
 
     P002 - Deckhand rendering is expected to complete without errors.
     P003 - All repos contain expected directories.
+
+
+.. _`Deckhand Validations`: http://deckhand.readthedocs.io/en/latest/validation.html

docs/source/getting_started.rst

@@ -21,23 +21,40 @@ Getting Started
 What is Pegleg?
 ---------------
 
-Pegleg is document aggregator that provides early linting and validations for
+Pegleg is a document aggregator that will aggregate all the documents in a
-documents that can be consumed by UCP.
+repository and pack them into a single YAML file. This allows for operators to
+structure their site definitions in a maintainable directory layout, while
+providing them with the automation and tooling needed to aggregate, lint, and
+render those documents for deployment.
 
 For more information on the documents that Pegleg works on see `Document Fundamentals`_.
 
 Basic Usage
 -----------
 
-Before using Pegleg, you must install the required packages in pegleg/src/bin/pegleg
+Before using Pegleg, you must:
+
+Clone the Pegleg repository
+
+.. code-block:: console
+
+    git clone https://github.com/att-comdev/pegleg
+
+and install the required packages in pegleg/src/bin/pegleg
 
 .. code-block:: console
 
      pip3 install -r pegleg/src/bin/pegleg/requirements.txt -r pegleg/src/bin/pegleg/test-requirements.txt
 
+Next, add your repos containing your `site definition libraries`_ into your
+local system where Pegleg is running, as Pegleg can only work on files available
+in the local directory.
 
 You will then be able to use all of Pegleg's features through the CLI. See CLI_ for more
 information.
 
 .. _Document Fundamentals: https://pegleg.readthedocs.io/en/latest/authoring_strategy.html
 .. _CLI: https://pegleg.readthedocs.io/en/latest/cli.html
+.. _Deckhand: http://deckhand.readthedocs.io/en/latest/
+.. _UCP: https://github.com/att-comdev/ucp-integration
+.. _site definition libraries: https://pegleg.readthedocs.io/en/latest/artifacts.html#definition-library-layout