From 7145bc25e10d61182debaae662b8f8a55a2f2549 Mon Sep 17 00:00:00 2001 From: Krysta Date: Thu, 8 Mar 2018 13:12:45 -0600 Subject: [PATCH] CLI documentation for Pegleg Change-Id: I1087e4ed6645faf197e3352d2981939c9e4f1ef4 --- docs/requirements.txt | 2 +- docs/source/authoring_strategy.rst | 10 +- docs/source/cli.rst | 145 +++++++++++++++++++++++++++++ docs/source/index.rst | 12 +-- tox.ini | 17 ++++ 5 files changed, 172 insertions(+), 14 deletions(-) create mode 100644 docs/source/cli.rst create mode 100644 tox.ini diff --git a/docs/requirements.txt b/docs/requirements.txt index ddc6a294..38d8f59d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ # Documentation sphinx>=1.6.2 -sphinx_rtd_theme==0.2.4 \ No newline at end of file +sphinx_rtd_theme==0.2.4 diff --git a/docs/source/authoring_strategy.rst b/docs/source/authoring_strategy.rst index 3e988e48..209e06ac 100644 --- a/docs/source/authoring_strategy.rst +++ b/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 ... - diff --git a/docs/source/cli.rst b/docs/source/cli.rst new file mode 100644 index 00000000..bab8a3b1 --- /dev/null +++ b/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 + + +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 -a + + Example: + ./pegleg.sh site -p /workspace/repo_1 -a /workspace/repo_2 + + +Collect +------- +Output complete config for one site + +**site_name** + +Name of the site. + +**-s / --save-location** + +Where to output. + +:: + + ./pegleg.sh 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 -a + -f -x -w + + 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 ** + +Will excluded the specified lint option. -w takes priority over -x. + +**-w ** + +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. diff --git a/docs/source/index.rst b/docs/source/index.rst index a9abdf14..44874f04 100644 --- a/docs/source/index.rst +++ b/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/ diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..479657a5 --- /dev/null +++ b/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