From 51ef7bfba71ddb99348246be43c419bdacd913d2 Mon Sep 17 00:00:00 2001 From: Michael Dowling Date: Mon, 12 Dec 2022 16:05:34 -0800 Subject: [PATCH] Improve docs and CLI summary output --- .../guides/building-models/build-config.rst | 23 ++++++++++--------- .../smithy/cli/commands/AstCommand.java | 2 +- .../smithy/cli/commands/CleanCommand.java | 2 +- .../smithy/cli/commands/DiffCommand.java | 2 +- .../smithy/cli/commands/SelectCommand.java | 2 +- .../smithy/cli/commands/ValidateCommand.java | 2 +- .../smithy/cli/commands/WarmupCommand.java | 2 +- 7 files changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/source-2.0/guides/building-models/build-config.rst b/docs/source-2.0/guides/building-models/build-config.rst index 0ea9ca83b3c..170182b56fc 100644 --- a/docs/source-2.0/guides/building-models/build-config.rst +++ b/docs/source-2.0/guides/building-models/build-config.rst @@ -41,14 +41,15 @@ The configuration file accepts the following properties: added as sources. Sources are relative to the configuration file. * - imports - ``[string]`` - - Provides a list of relative imports to combine into a single model. - Imports are a kind of local dependency: they aren't considered part of - model being built, but are required to build the model. When a - directory is encountered, all files in the entire directory tree are - imported. Note that build systems MAY choose to rely on other - mechanisms for importing models and forming a composite model. - Imports defined at the top-level are used in every projection. Imports - are relative to the configuration file. + - Provides a list of model files and directories to load when validating + and building the model. Imports are a local dependency: they are not + considered part of model package being built, but are required to build + the model package. Models added through ``imports`` are not present in + the output of the built-in ``sources`` plugin. + + When a directory is encountered, all files in the entire directory + tree are imported. Imports defined at the top-level are used in every + projection. Imports are relative to the configuration file. * - projections - ``map`` - A map of projection names to projection configurations. @@ -162,7 +163,7 @@ Maven picks the highest version of each project that satisfies all the hard requirements of the dependencies on that project. If no version satisfies all the hard requirements, dependency resolution fails. -The following table defines version requirement syntax as defined in +The following table demonstrates version requirement syntax as defined in the `official Maven documentation`_: .. list-table:: Dependency version syntax @@ -231,7 +232,7 @@ the following configuration: file. Instead, use :ref:`environment variables ` to keep credentials out of source control. -.. code-block:: +.. code-block:: json { "version": "1.0", @@ -256,7 +257,7 @@ SMITHY_MAVEN_REPOS environment variable When using the Smithy CLI, the ``SMITHY_MAVEN_REPOS`` environment variable can be used to configure Maven repositories automatically. The -``SMITHY_MAVEN_REPOS`` environment variable is a pipe-delimited value ("|") +``SMITHY_MAVEN_REPOS`` environment variable is a pipe-delimited value (``|``) that contains the URL of each repository to use. .. code-block:: diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/AstCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/AstCommand.java index 8837860ae7a..4fb243b1039 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/AstCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/AstCommand.java @@ -36,7 +36,7 @@ public String getName() { @Override public String getSummary() { - return "Reads Smithy models in and writes out a single JSON AST model"; + return "Reads Smithy models in and writes out a single JSON AST model."; } @Override diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/CleanCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/CleanCommand.java index a67841babff..2bd6c1584f0 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/CleanCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/CleanCommand.java @@ -46,7 +46,7 @@ public String getName() { @Override public String getSummary() { - return "Removes Smithy build artifacts"; + return "Removes Smithy build artifacts."; } @Override diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/DiffCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/DiffCommand.java index 73212a7143e..0f6a0a63628 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/DiffCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/DiffCommand.java @@ -50,7 +50,7 @@ public String getName() { @Override public String getSummary() { - return "Diffs two Smithy models and reports any significant changes"; + return "Compares two Smithy models and reports any significant changes."; } private static final class Options implements ArgumentReceiver { diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/SelectCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/SelectCommand.java index 1511c7fd322..44630058b38 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/SelectCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/SelectCommand.java @@ -52,7 +52,7 @@ public String getName() { @Override public String getSummary() { - return "Queries a model using a selector"; + return "Queries a model using a selector."; } @Override diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/ValidateCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/ValidateCommand.java index c8e7a10fd3a..a85da6d44b2 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/ValidateCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/ValidateCommand.java @@ -37,7 +37,7 @@ public String getName() { @Override public String getSummary() { - return "Validates Smithy models"; + return "Validates Smithy models."; } @Override diff --git a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/WarmupCommand.java b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/WarmupCommand.java index 710a52911ad..a5fb60a1de2 100644 --- a/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/WarmupCommand.java +++ b/smithy-cli/src/main/java/software/amazon/smithy/cli/commands/WarmupCommand.java @@ -45,7 +45,7 @@ public String getName() { @Override public String getSummary() { - return "Creates caches for faster subsequent executions"; + return "Creates caches for faster subsequent executions."; } @Override