diff --git a/docs/source/authoring_strategy.rst b/docs/source/authoring_strategy.rst index b4bb8823..b148cbf7 100644 --- a/docs/source/authoring_strategy.rst +++ b/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 -document is identified by a ``schema`` top-level key and the ``metadata.name`` -value that uniquely identifies a particular document of the type ``schema``. -Deckhand provides functionality allowing documents to be authored such that -data from multiple documents can be merged. +are managed by Deckhand_. Each document is identified by a ``schema`` top-level +key and the ``metadata.name`` value that uniquely identifies a particular +document of the type ``schema``. Deckhand provides functionality allowing +documents to be authored such that 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 -_types http://deckhand.readthedocs.io/en/latest/document_types.html#provided-utility-document-kinds -exist to support storing sensitive data encrypted. +Several generic document types_ 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 ------------ diff --git a/docs/source/cli.rst b/docs/source/cli.rst index 8ad12303..d48db5d2 100644 --- a/docs/source/cli.rst +++ b/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 +.. code-block:: console + + export WORKSPACE= + export IMAGE= + ./pegleg.sh 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 -been corrected already. +Output complete config for one site. +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 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index f629c0e0..98547407 100644 --- a/docs/source/getting_started.rst +++ b/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 -documents that can be consumed by UCP. +Pegleg is a document aggregator that will aggregate all the documents in a +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