CLI documentation for Pegleg

Change-Id: I1087e4ed6645faf197e3352d2981939c9e4f1ef4

docs/requirements.txt

@@ -1,3 +1,3 @@
 # Documentation
 sphinx>=1.6.2
-sphinx_rtd_theme==0.2.4
+sphinx_rtd_theme==0.2.4

docs/source/authoring_strategy.rst

@@ -49,7 +49,7 @@ These must be utilized for all data considered sensitive.
 Global Catalogue Documents
 --------------------------
 
-Deckhand's layering functionality can be utilized in several ways, but AIC
+`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
@@ -84,9 +84,12 @@ to ensure you understand all the requirements for it.
 This catalogue pattern can also be utilized for the ``type`` layer
 if needed.
 
+.. _Deckhand: https://deckhand.readthedocs.io
+
 Global Layer
 ------------
-.. highlight:: yaml
+
+.. code-block:: yaml
 
     ---
     schema: armada/Chart/v1
@@ -263,7 +266,7 @@ Global Layer
 Site Layer
 ----------
 
-.. highlight:: yaml
+.. code-block:: yaml
 
     ---
     schema: armada/Chart/v1
@@ -350,4 +353,3 @@ Site Layer
       storagePolicy: cleartext
     data: myuser
     ...
-

docs/source/cli.rst

@@ -0,0 +1,145 @@
+..
+      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.
+
+==========
+Pegleg CLI
+==========
+
+The Pegleg CLI is used in conjunction with the script located in pegleg/tools
+called pegleg.sh.
+
+::
+
+    $WORKSPACE = Location of the folder that holds the repositories containing
+    the site definition libraries. Pegleg makes no assumption about the root
+    directory. $WORKSPACE is /workspace in the container context.
+
+    $IMAGE = Location of pegleg docker image.
+
+To run:
+
+./pegleg.sh <command> <options>
+
+
+CLI Options
+===========
+
+\ -v / --verbose
+Enable debug logging.
+
+Site
+----
+Commands related to sites.
+
+**-p / --primary**
+
+Path to the root of the primary (containing site_definition.yaml) repo.
+(Required).
+
+**-a / --auxiliary**
+
+Path to the root of an auxiliary repo.
+
+::
+
+    ./pegleg.sh site -p <primary_repo> -a <auxiliary_repo> <command> <options>
+
+    Example:
+    ./pegleg.sh site -p /workspace/repo_1 -a /workspace/repo_2
+    <command> <options>
+
+Collect
+-------
+Output complete config for one site
+
+**site_name**
+
+Name of the site.
+
+**-s / --save-location**
+
+Where to output.
+
+::
+
+    ./pegleg.sh <command> <options> collect site_name -s save_location
+
+    Example:
+    ./pegleg.sh site -p /workspace/repo_1 -a /workspace/repo_2
+    collect site_name -s /workspace
+
+Impacted
+--------
+Find sites impacted by changed files.
+
+**-i / --input**
+
+List of impacted files
+
+**-o / --output**
+
+Lint
+----
+Sanity checks for repository content.
+
+::
+
+    ./pegleg.sh lint -p <primary_repo> -a <auxiliary_repo>
+    -f -x <lint_code> -w <lint_code>
+
+    Example:
+
+    ./pegleg.sh lint -p /workspace/site-repo -a /workspace/secondary-repo
+    -x P001 -x P002 -w P003
+
+**-p / --primary**
+
+Path to the root of the primary (containing site_definition.yaml) repo.
+(Required).
+
+**-a / --auxiliary**
+
+Path to the root of an auxiliary repo.
+
+**-f / --fail-on-missing-sub-src**
+
+Raise Deckhand exception on missing substitution sources. Defaults to True.
+
+**-x <code>**
+
+Will excluded the specified lint option. -w takes priority over -x.
+
+**-w <code>**
+
+Will warn of lint failures from the specified lint options.
+
+::
+
+    If you expect certain lint failures, then those lint options can be
+    excluded or you can choose to be warned about those failures using the
+    codes below.
+
+    P001 - Document has storagePolicy cleartext (expected is encrypted) yet
+    its schema is a mandatory encrypted type.
+
+    Where mandatory encrypted schema type is one of:
+    * deckhand/CertificateAuthorityKey/v1
+    * deckhand/CertificateKey/v1
+    * deckhand/Passphrase/v1
+    * deckhand/PrivateKey/v1
+
+    P002 - Deckhand rendering is expected to complete without errors.
+    P003 - All repos contain expected directories.

docs/source/index.rst

@@ -22,9 +22,8 @@
 Building this Documentation
 ---------------------------
 
-Use of ``sphinx-build -b html docs/source docs/build`` will build a html
-version of this documentation that can be viewed using a browser at
-docs/build/index.html on the local filesystem.
+Use of ``tox -e docs`` will build an HTML version of this documentation that
+can be viewed using a browser at docs/build/index.html on the local filesystem.
 
 Conventions and Standards
 -------------------------
@@ -34,11 +33,6 @@ Conventions and Standards
 
    authoring_strategy
    artifacts
+   cli
 
-
-.. _Helm: https://helm.sh/
-.. _Kubernetes: https://kubernetes.io/
-.. _Openstack: https://www.openstack.org/
-.. _Openstack Helm: https://github.com/openstack/openstack-helm
 .. _Treasuremap: https://github.com/att-comdev/treasuremap
-.. _yaml: http://yaml.org/

tox.ini

@@ -0,0 +1,17 @@
+[tox]
+envlist = docs
+# Allows docs to be built without setup.py having to exist. Requires that
+# usedevelop be False as well (which it is by default).
+skipsdist = True
+
+[testenv]
+setenv = VIRTUAL_ENV={envdir}
+         LANGUAGE=en_US
+         LC_ALL=en_US.utf-8
+
+[testenv:docs]
+deps = -r{toxinidir}/docs/requirements.txt
+commands =
+    rm -rf doc/build
+    sphinx-build -b html docs/source docs/build -n -W -v
+whitelist_externals = rm