Merge pull request #526 from dgraeber/fix/adding-cli-docs

adding cli detail documentation

CHANGELOG.md

@@ -9,6 +9,7 @@ This project adheres to [Semantic Versioning](http://semver.org/) and [Keep a Ch
 
 ### Changes
 - renaming the threads spawned for deploy / destroy to indicate the module being worked on
+- adding detailed docs for CLI parameters
 
 ### Fixes
 

docs/requirements-docs.in

@@ -7,6 +7,7 @@ sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
+sphinx-click==5.1.0
 myst_parser==1.0.0
 docutils~=0.16
 PyYAML==5.4

docs/requirements-docs.txt

@@ -16,11 +16,14 @@ certifi==2023.7.22
     #   requests
 charset-normalizer==3.1.0
     # via requests
+click==8.1.7
+    # via sphinx-click
 docutils==0.18.1
     # via
     #   -r requirements-docs.in
     #   myst-parser
     #   sphinx
+    #   sphinx-click
     #   sphinx-rtd-theme
 idna==3.4
     # via requests
@@ -64,10 +67,13 @@ sphinx==6.2.1
     # via
     #   myst-parser
     #   sphinx-autoapi
+    #   sphinx-click
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
 sphinx-autoapi==2.1.0
     # via -r requirements-docs.in
+sphinx-click==5.1.0
+    # via -r requirements-docs.in
 sphinx-rtd-theme==1.2.1
     # via -r requirements-docs.in
 sphinxcontrib-applehelp==1.0.4

docs/source/cli_commands.md → docs/source/cli_commands.md_bak

@@ -77,4 +77,4 @@ NOTE: if you run the SeedFarmer CLI with the `--debug` flag, you can see what th
 
 ```code
 [2023-05-11 12:54:48,392 | DEBUG | _service_utils.py: 32 | MainThread ] Proxies Configured: {'http': None, 'https': 'http://mygreatserver:8899'}
-```
+```

docs/source/cli_commands.rst

@@ -0,0 +1,142 @@
+
+####################################
+CLI (Command Line Interface)
+####################################
+
+The seedfarmer CLI provides the primary way to interface with the orchestration framework that manages a deploymement with AWS CodeSeeder. 
+It is used by CICD pipelines and individual users to:
+ - deploy code (modules) via a deployment and manifest
+ - fetch metadata related to currently deployed modules
+ - destroy deployments
+ - apply changes to deployments (via a GitOps model)
+
+-------------------
+HTTP Proxy Support
+-------------------
+
+SeedFarmer does support the use of an HTTP-Proxy.  It is invoked via setting an environment variable in the context of where the CLI is being invoked.  SeedFarmer always leverages HTTPS for its boto3 invocations, so be sure to set the proper parameter.
+
+The parameter we recognize is `HTTPS_PROXY` .  To set it for your runtime, you can do the folllowing (prior to invoking the CLI):
+
+``export HTTPS_PROXY=https://<server>:<port>``
+
+For example, my server DNS is `mygreatserver.com` and is listening on port `8899` 
+
+``export HTTPS_PROXY=http://mygreatserver.com:8899``
+
+In the above example, you will notice that my proxy is NOT over HTTPS....but the `HTTPS_PROXY` variable is being set.  This is correct, as SeedFarmer is leverging HTTPS for is invocation, regardless of your proxy configuration (it is up to you to determine the proper endpoint).
+
+NOTE: if you run the SeedFarmer CLI with the `--debug` flag, you can see what the proxy is being configured for:
+
+``[2023-05-11 12:54:48,392 | DEBUG | _service_utils.py: 32 | MainThread ] Proxies Configured: {'http': None, 'https': 'http://mygreatserver:8899'}``
+
+-------------------
+Summary of Commands
+-------------------
+
+..
+  main commands
+
+.. click:: seedfarmer.__main__:apply
+   :prog: seedfarmer apply
+   :nested: full
+
+.. click:: seedfarmer.__main__:destroy
+   :prog: seedfarmer destroy
+   :nested: full
+
+..
+  list commands
+.. click:: seedfarmer.cli_groups._list_group:list_dependencies
+   :prog: seedfarmer list dependencies
+   :nested: full
+
+.. click:: seedfarmer.cli_groups._list_group:list_deployspec    
+    :prog: seedfarmer list deployspec
+    :nested: full
+.. click:: seedfarmer.cli_groups._list_group:list_module_metadata
+    :prog: seedfarmer list moduledata
+    :nested: full
+.. click:: seedfarmer.cli_groups._list_group:list_all_module_metadata 
+    :prog: seedfarmer list allmoduledata
+    :nested: full
+.. click:: seedfarmer.cli_groups._list_group:list_modules 
+    :prog: seedfarmer list modules
+    :nested: full
+.. click:: seedfarmer.cli_groups._list_group:list_deployments 
+    :prog: seedfarmer list deployments
+    :nested: full
+.. click:: seedfarmer.cli_groups._list_group:list_build_env_params 
+    :prog: seedfarmer list buildparams 
+    :nested: full  
+
+..
+  bootstrap commands
+  
+  
+.. click:: seedfarmer.cli_groups._bootstrap_group:bootstrap_toolchain 
+    :prog: seedfarmer bootstrap toolchain
+    :nested: full  
+
+.. click:: seedfarmer.cli_groups._bootstrap_group:bootstrap_target 
+    :prog: seedfarmer bootstrap target
+    :nested: full  
+
+..
+  init commands
+
+.. click:: seedfarmer.cli_groups._init_group:init_module
+    :prog: seedfarmer init module
+    :nested: full
+
+.. click:: seedfarmer.cli_groups._init_group:init_project
+    :prog: seedfarmer init project
+    :nested: full  
+
+..
+  project commands
+  
+.. click:: seedfarmer.cli_groups._project_group:policy_synth
+    :prog: seedfarmer projectpolicy synth
+    :nested: full  
+
+..
+  metadata commands
+.. click:: seedfarmer.cli_groups._manage_metadata_group:convert_cdkexports
+    :prog: seedfarmer metadata convert
+    :nested: full  
+
+
+.. click:: seedfarmer.cli_groups._manage_metadata_group:add
+    :prog: seedfarmer metadata add
+    :nested: full  
+
+.. click:: seedfarmer.cli_groups._manage_metadata_group:depmod
+    :prog: seedfarmer metadata depmod
+    :nested: full  
+
+.. click:: seedfarmer.cli_groups._manage_metadata_group:param_value
+    :prog: seedfarmer metadata paramvalue
+    :nested: full  
+
+
+.. 
+  remove commands
+.. click:: seedfarmer.cli_groups._remove_group:remove_module_data
+    :prog: seedfarmer remove moduledata
+    :nested: full  
+
+
+.. 
+  store commands
+.. click:: seedfarmer.cli_groups._store_group:store_deployspec
+    :prog: seedfarmer store deployspec
+    :nested: full
+
+.. click:: seedfarmer.cli_groups._store_group:store_module_metadata
+    :prog: seedfarmer store moduledata
+    :nested: full  
+
+.. click:: seedfarmer.cli_groups._store_group:store_module_md5
+    :prog: seedfarmer store md5
+    :nested: full  

docs/source/conf.py

@@ -33,7 +33,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autosectionlabel", "sphinx.ext.napoleon", "myst_parser", "autoapi.extension"]
+extensions = ["sphinx.ext.autosectionlabel", "sphinx.ext.napoleon", "myst_parser", "autoapi.extension","sphinx_click.ext"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

seedfarmer/__main__.py

@@ -47,26 +47,30 @@ def version() -> None:
 @click.option(
     "--profile",
     default=None,
-    help="The AWS profile to use for boto3.Sessions",
+    help="The AWS profile used to create a session to assume the toolchain role",
     required=False,
 )
 @click.option(
     "--region",
     default=None,
-    help="The AWS region to use for boto3.Sessions",
+    help="The AWS region used to create a session to assume the toolchain role",
     required=False,
 )
 @click.option(
     "--qualifier",
     default=None,
-    help="A qualifier to append to toolchain / target roles",
+    help="""A qualifier to use with the seedfarmer roles.
+    Use only if bootstrapped with this qualifier""",
     required=False,
 )
 @click.option(
     "--env-file",
     "env_files",
     default=[".env"],
-    help="A relative path to the .env file to load environment variables from",
+    help="""A relative path to the .env file to load environment variables from.
+    Multple files can be passed in by repeating this flag, and the order will be
+    preserved when overriding duplicate values.
+    """,
     multiple=True,
     required=False,
 )
@@ -87,7 +91,7 @@ def version() -> None:
 @click.option(
     "--show-manifest/--no-show-manifest",
     default=False,
-    help="Write out the generated deployment manifest",
+    help="Write out the generated deployment manifest to console",
     show_default=True,
     type=bool,
 )
@@ -108,14 +112,14 @@ def version() -> None:
 @click.option(
     "--update-seedkit/--no-update-seedkit",
     default=False,
-    help="Force SeedFarmer to update the SeedKit if found",
+    help="Force SeedFarmer to update the SeedKit when invoked",
     show_default=True,
     type=bool,
 )
 @click.option(
     "--update-project-policy/--no-update-project-policy",
     default=False,
-    help="Force SeedFarmer to update the deployed Project Policy",
+    help="Force SeedFarmer to update the deployed Project Policy when invoked",
     show_default=True,
     type=bool,
 )
@@ -179,26 +183,30 @@ def apply(
 @click.option(
     "--profile",
     default=None,
-    help="The AWS profile to use for boto3.Sessions",
+    help="The AWS profile used to create a session to assume the toolchain role",
     required=False,
 )
 @click.option(
     "--region",
     default=None,
-    help="The AWS region to use for toolchain",
+    help="The AWS region used to create a session to assume the toolchain role",
     required=False,
 )
 @click.option(
     "--qualifier",
     default=None,
-    help="A qualifier to append to toolchain / target role",
+    help="""A qualifier to use with the seedfarmer roles.
+    Use only if bootstrapped with this qualifier""",
     required=False,
 )
 @click.option(
     "--env-file",
     "env_files",
     default=[".env"],
-    help="A relative path to the .env file to load environment variables from",
+    help="""A relative path to the .env file to load environment variables from.
+    Multple files can be passed in by repeating this flag, and the order will be
+    preserved when overriding duplicate values.
+    """,
     multiple=True,
     required=False,
 )

seedfarmer/cli_groups/_bootstrap_group.py

@@ -79,26 +79,27 @@ def bootstrap() -> None:
     "--synth/--no-synth",
     type=bool,
     default=False,
-    help="Synthesize a CFN template only...do not deploy",
+    help="Synthesize a CFN bootstrap template only...do not deploy",
     required=False,
     show_default=True,
 )
 @click.option(
     "--profile",
     default=None,
-    help="The AWS profile to initiate a session",
+    help="The AWS profile to use to initiate a session",
     required=False,
 )
 @click.option(
     "--region",
     default=None,
-    help="AWS region to use",
+    help="AWS region to use to initiate a session",
     required=False,
 )
 @click.option(
     "--qualifier",
     default=None,
-    help="A qualifier to append to toolchain role (alpha-numeric char max length of 6)",
+    help="""A qualifier to append to toolchain role (alpha-numeric char max length of 6).
+    If used, it MUST be used on every seedfarmer command.""",
     required=False,
 )
 @click.option(
@@ -181,19 +182,20 @@ def bootstrap_toolchain(
 @click.option(
     "--profile",
     default=None,
-    help="The AWS profile to initiate a session",
+    help="The AWS profile to use to initiate a session",
     required=False,
 )
 @click.option(
     "--region",
     default=None,
-    help="AWS region to use",
+    help="AWS region to use to initiate a session",
     required=False,
 )
 @click.option(
     "--qualifier",
     default=None,
-    help="A qualifier to append to target role (alpha-numeric char max length of 6)",
+    help="""A qualifier to append to target role (alpha-numeric char max length of 6).
+    If used on the toolchain account, it should be used here!""",
     required=False,
 )
 @click.option(