diff --git a/README.md b/README.md index f4e2e84a..d2c3dca5 100644 --- a/README.md +++ b/README.md @@ -1 +1,9 @@ -# pegleg \ No newline at end of file +# 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) diff --git a/docs/source/authoring_strategy.rst b/docs/source/authoring_strategy.rst index 209e06ac..b4bb8823 100644 --- a/docs/source/authoring_strategy.rst +++ b/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 diff --git a/docs/source/cli.rst b/docs/source/cli.rst index bab8a3b1..8ad12303 100644 --- a/docs/source/cli.rst +++ b/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 -o + +List +---- +List known sites. + +**-o/--output** + +Where to output. + +:: + + ./pegleg 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 show site_name + + Example: + ./pegleg site -p /workspace/repo_1 show site_name -o /workspace + + + Lint ---- Sanity checks for repository content. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 00000000..f629c0e0 --- /dev/null +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 44874f04..d4f879a1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,7 @@ Conventions and Standards .. toctree:: :maxdepth: 2 + getting_started authoring_strategy artifacts cli