airship
/
pegleg
Code Issues Proposed changes

Pegleg documentation updates 

This patch:
1. Moves defaults for flags in line with the flag for improved
   readability.
2. Removes an example that does not apply to that command.

Change-Id: I16575924c6c7cd6389a70cd687a21c2857889d03
This commit is contained in:
Alexander Hughes 2019-05-16 10:39:11 -05:00
parent 4593523dd2
commit 6375158fc1
1 changed files with 44 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
doc/source/cli/cli.rst
View File

@ -77,7 +77,7 @@ For example:
CLI Options CLI Options
=========== ===========
**-v / --verbose** (Optional). False by default. **-v / --verbose** (Optional, Default=False).
Enable debug logging. Enable debug logging.
@ -103,15 +103,15 @@ The revision can also be specified via (for example):
-r /opt/airship-treasuremap@revision -r /opt/airship-treasuremap@revision
**-p / --clone-path** (Optional). **-p / --clone-path** (Optional, Default=/tmp/).
The path where the repo will be cloned. By default the repo will be cloned to The path where the repo will be cloned. If this option is included and the
the /tmp path. If this option is included and the repo already exists, then the repo already exists, then the repo will not be cloned again and the user must
repo will not be cloned again and the user must specify a new clone path or specify a new clone path or pass in the local copy of the repository as the
pass in the local copy of the repository as the site repository. Suppose the site repository. Suppose the repo name is airship-treasuremap and the clone
repo name is airship-treasuremap and the clone path is /tmp/mypath then the path is /tmp/mypath then the following directory is created
following directory is created /tmp/mypath/airship-treasuremap which will /tmp/mypath/airship-treasuremap which will contain the contents of the repo.
contain the contents of the repo. Example of using clone path: Example of using clone path:
:: ::
@ -164,15 +164,15 @@ These should be named per the site-definition file, e.g.:
-e global=/opt/global -e secrets=/opt/secrets -e global=/opt/global -e secrets=/opt/secrets
**-p / --clone-path** (Optional). **-p / --clone-path** (Optional, Default=/tmp/).
The path where the repo will be cloned. By default the repo will be cloned to The path where the repo will be cloned. If this option is included and the
the /tmp path. If this option is included and the repo already exists, then the repo already exists, then the repo will not be cloned again and the user must
repo will not be cloned again and the user must specify a new clone path or specify a new clone path or pass in the local copy of the repository as the
pass in the local copy of the repository as the site repository. Suppose the site repository. Suppose the repo name is airship-treasuremap and the clone
repo name is airship-treasuremap and the clone path is /tmp/mypath then the path is /tmp/mypath then the following directory is created
following directory is created /tmp/mypath/airship-treasuremap which will /tmp/mypath/airship-treasuremap which will contain the contents of the repo.
contain the contents of the repo. Example of using clone path: Example of using clone path:
:: ::
@ -231,15 +231,15 @@ Name of the site.
Where to output collected documents. If omitted, the results will be dumped Where to output collected documents. If omitted, the results will be dumped
to ``stdout``. to ``stdout``.
**-x <code>** (Optional, validation only). **-x** (Optional, validation only).
Will exclude the specified lint option. -w takes priority over -x. Will exclude the specified lint option. -w takes priority over -x.
**-w <code>** (Optional, validation only). **-w** (Optional, validation only).
Will warn of lint failures from the specified lint options. Will warn of lint failures from the specified lint options.
**--validate** (Optional, validation only). False by default. **--validate** (Optional, validation only, Default=False).
Perform validation of documents prior to collection. See :ref:`cli-site-lint` Perform validation of documents prior to collection. See :ref:`cli-site-lint`
for additional information on document linting. It is recommended that document for additional information on document linting. It is recommended that document
@ -277,7 +277,7 @@ List
List known sites. List known sites.
**-o/--output** (Optional). **-o / --output** (Optional, Default=stdout).
Where to output. Where to output.
@ -285,8 +285,6 @@ Where to output.
./pegleg <command> <options> list ./pegleg <command> <options> list
Results are dumped to ``stdout`` by default.
Examples Examples
^^^^^^^^ ^^^^^^^^
@ -305,7 +303,7 @@ Show details for one site.
Name of site. Name of site.
**-o/--output** (Optional). **-o / --output** (Optional, Default=stdout).
Where to output. Where to output.
@ -313,8 +311,6 @@ Where to output.
./pegleg <command> <options> show site_name ./pegleg <command> <options> show site_name
Results are dumped to ``stdout`` by default.
Examples Examples
^^^^^^^^ ^^^^^^^^
@ -333,11 +329,11 @@ Render documents via `Deckhand`_ for one site.
Name of site. Name of site.
**-o/--output** (Optional). **-o / --output** (Optional, Default=stdout).
Where to output. Where to output.
**-v/--validate** (Optional). Default is True. **-v / --validate** (Optional, Default=True).
Whether to pre-validate documents using built-in schema validation. Whether to pre-validate documents using built-in schema validation.
Skips over externally registered DataSchema documents to avoid Skips over externally registered DataSchema documents to avoid
@ -347,8 +343,6 @@ false positives.
./pegleg <command> <options> render site_name ./pegleg <command> <options> render site_name
Results are dumped to ``stdout`` by default.
Examples Examples
^^^^^^^^ ^^^^^^^^
@ -407,7 +401,7 @@ Uploads documents to `Shipyard`_.
Name of the site. The ``site_name`` must match a ``site`` name in the site Name of the site. The ``site_name`` must match a ``site`` name in the site
repository folder structure repository folder structure
**--os-<various>=<value>** (Required). **--os-<various>** (Required).
Shipyard needs these options for authenticating with OpenStack Keystone. Shipyard needs these options for authenticating with OpenStack Keystone.
This option can be set as environment variables or it can be passed via This option can be set as environment variables or it can be passed via
@ -415,12 +409,12 @@ the command line.
Please reference Shipyard's `CLI documentation`_ for information related to these options. Please reference Shipyard's `CLI documentation`_ for information related to these options.
**--context-marker=<uuid>** (Optional). **--context-marker** (Optional).
Specifies a UUID (8-4-4-4-12 format) that will be used to correlate logs, Specifies a UUID (8-4-4-4-12 format) that will be used to correlate logs,
transactions, etc. in downstream activities triggered by this interaction. transactions, etc. in downstream activities triggered by this interaction.
**-b / --buffer-mode** (Optional). Default is auto. **-b / --buffer-mode** (Optional, Default=auto).
Set the buffer mode when uploading documents. Supported buffer modes Set the buffer mode when uploading documents. Supported buffer modes
include append, replace, auto. include append, replace, auto.
@ -496,10 +490,10 @@ Dashes in the document names will be converted to underscores for consistency.
Name of site. Name of site.
**-d / --days** (Optional). **-d / --days** (Optional, Default=365).
Duration (in days) certificates should be valid. Default=365, Duration (in days) certificates should be valid.
minimum=0, no maximum. Values less than 0 will raise an exception. Minimum=0, no maximum. Values less than 0 will raise an exception.
NOTE: A generated certificate where days = 0 should only be used for testing. NOTE: A generated certificate where days = 0 should only be used for testing.
A certificate generated in such a way will be valid for 0 seconds. A certificate generated in such a way will be valid for 0 seconds.
@ -507,12 +501,6 @@ A certificate generated in such a way will be valid for 0 seconds.
Examples Examples
"""""""" """"""""
::
./pegleg.sh site -r <site_repo> -e <extra_repo> \
upload <site_name> <options>
:: ::
./pegleg.sh site -r <site_repo> -e <extra_repo> \ ./pegleg.sh site -r <site_repo> -e <extra_repo> \
@ -532,10 +520,10 @@ Determine if any PKI certificates from a site are expired, or will be expired
within ``days`` days. If any are found, print the cert names and expiration within ``days`` days. If any are found, print the cert names and expiration
dates to ``stdout``. dates to ``stdout``.
**-d / --days** (Optional). **-d / --days** (Optional, Default=60).
Duration (in days) to check certificate validity from today. Default=60, Duration (in days) to check certificate validity from today.
minimum=0, no maximum. Values less than 0 will raise an exception. Minimum=0, no maximum. Values less than 0 will raise an exception.
NOTE: Checking PKI certs where days = 0 will check for certs that are expired NOTE: Checking PKI certs where days = 0 will check for certs that are expired
at the time the command is run. at the time the command is run.
@ -752,9 +740,9 @@ The name for the document to be wrapped, e.g. new-cert.
The layer for the document to be wrapped, e.g. site. The layer for the document to be wrapped, e.g. site.
**--encrypt / --no-encrypt** **--encrypt / --no-encrypt** (Default=True).
A flag specifying whether to encrypt the output file. (default: True) A flag specifying whether to encrypt the output file.
Examples Examples
"""""""" """"""""
@ -783,7 +771,7 @@ Constructs genesis bundle based on a site configuration.
Destination directory for the genesis bundle. Destination directory for the genesis bundle.
**--include-validators** (Optional). False by default. **--include-validators** (Optional, Default=False).
A flag to request build genesis validation scripts as well. A flag to request build genesis validation scripts as well.
@ -965,15 +953,15 @@ Valid Git references for checking out repositories include:
Linting Linting
======= =======
**-f / --fail-on-missing-sub-src** (Optional). **-f / --fail-on-missing-sub-src** (Optional, Default=True).
Raise Deckhand exception on missing substitution sources. Defaults to True. Raise Deckhand exception on missing substitution sources.
**-x <code>** (Optional). **-x** (Optional).
Will exclude the specified lint option. -w takes priority over -x. Will exclude the specified lint option. -w takes priority over -x.
**-w <code>** (Optional). **-w** (Optional).
Will warn of lint failures from the specified lint options. Will warn of lint failures from the specified lint options.
@ -1013,9 +1001,9 @@ Passphrase
Generate a passphrase and print to ``stdout``. Generate a passphrase and print to ``stdout``.
**-l / --length** (Optional). **-l / --length** (Optional, Default=24).
Length of passphrase to generate. By default length is 24. Length of passphrase to generate.
Minimum length is 24. Lengths less than minimum will default to 24. Minimum length is 24. Lengths less than minimum will default to 24.
No maximum length. No maximum length.
@ -1045,9 +1033,9 @@ Salt
Generate a salt and print to ``stdout``. Generate a salt and print to ``stdout``.
**-l / --length** (Optional). **-l / --length** (Optional, Default=24).
Length of salt to generate. By default length is 24. Length of salt to generate.
Minimum length is 24. Lengths less than minimum will default to 24. Minimum length is 24. Lengths less than minimum will default to 24.
No maximum length. No maximum length.