Pegleg documentation updates

-Add Geeting started guide
-Add missing cli options
-fix some wording
-fix typos
-add Readme

Change-Id: Ifbbb15aa212936a95167d2bca696830ed2408b93

README.md

@@ -1 +1,9 @@
-# pegleg
+# Pegleg
+
+Pegleg is document aggregator that provides early linting and validations via
+[Deckhand](http://deckhand.readthedocs.io/en/latest/) for documents that can be consumed by UCP. To learn more about UCP
+see [UCP Integration](https://github.com/att-comdev/ucp-integration)
+
+
+## Getting Started
+To get started, see [getting started](https://pegleg.readthedocs.io/en/latest/getting_started.html)

docs/source/authoring_strategy.rst

@@ -49,16 +49,15 @@ These must be utilized for all data considered sensitive.
 Global Catalogue Documents
 --------------------------
 
-`Deckhand`_'s layering functionality can be utilized in several ways, but AIC
-site definitions will use a 'catalogue' approach. At the ``global`` layer
-there will be several documents providing different configurations for an
-object or service. Each of these will be abstract documents. They can be
-incorporated into a particular site definition by creating a concrete
-child document in the ``site`` layer that selects the correct ``global``
-parent. The child can then do further customization on the configuration if
-needed.
+`Deckhand`_'s layering functionality can be utilized in several ways, i.e site
+definitions. At the ``global`` layer there will be several documents providing
+different configurations for an object or service. Each of these will be
+abstract documents. They can be incorporated into a particular site definition
+by creating a concrete child document in the ``site`` layer that selects the
+correct ``global`` parent. The child can then do further customization on the
+configuration if needed.
 
-As a best practice, ``global`` level documents using the catalogue pattern
+As a best practice, ``global`` level documents using the catalog pattern
 should utilize the layering labels ``component`` and ``configuration`` to
 provide a consistent method for children documents select the correct parent.
 The below example shows a set  of documents for two configuration options for

docs/source/cli.rst

@@ -24,7 +24,7 @@ called pegleg.sh.
 ::
 
     $WORKSPACE = Location of the folder that holds the repositories containing
-    the site definition libraries. Pegleg makes no assumption about the root
+    the site definition libraries. Pegleg makes no assumptions about the root
     directory. $WORKSPACE is /workspace in the container context.
 
     $IMAGE = Location of pegleg docker image.
@@ -37,7 +37,8 @@ To run:
 CLI Options
 ===========
 
-\ -v / --verbose
+**-v / --verbose**
+
 Enable debug logging.
 
 Site
@@ -63,11 +64,12 @@ Path to the root of an auxiliary repo.
 
 Collect
 -------
-Output complete config for one site
+Output complete config for one site. It is assumed that all lint errors have
+been corrected already.
 
 **site_name**
 
-Name of the site.
+Name of the site. (Required).
 
 **-s / --save-location**
 
@@ -87,10 +89,52 @@ Find sites impacted by changed files.
 
 **-i / --input**
 
-List of impacted files
+List of impacted files.
 
 **-o / --output**
 
+Where to output.
+
+::
+
+    ./pegleg impacted -i <input_stream> -o <output_stream>
+
+List
+----
+List known sites.
+
+**-o/--output**
+
+Where to output.
+
+::
+
+    ./pegleg <command> <options> list
+
+    Example:
+    ./pegleg site -p /workspace/repo_1 list -o /workspace
+
+Show
+----
+Show details for one site.
+
+**site_name**
+
+Name of site. (Required).
+
+**-o /--output**
+
+Where to output.
+
+::
+
+    ./pegleg <command> <options> show site_name
+
+    Example:
+    ./pegleg site -p /workspace/repo_1 show site_name -o /workspace
+
+
+
 Lint
 ----
 Sanity checks for repository content.

docs/source/getting_started.rst

@@ -0,0 +1,43 @@
+..
+      Copyright 2018 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+===============
+Getting Started
+===============
+
+What is Pegleg?
+---------------
+
+Pegleg is document aggregator that provides early linting and validations for
+documents that can be consumed by UCP.
+
+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
+
+.. code-block:: console
+
+     pip3 install -r pegleg/src/bin/pegleg/requirements.txt -r pegleg/src/bin/pegleg/test-requirements.txt
+
+
+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

docs/source/index.rst

@@ -31,6 +31,7 @@ Conventions and Standards
 .. toctree::
    :maxdepth: 2
 
+   getting_started
    authoring_strategy
    artifacts
    cli