feat: generate CLI README.md (#1075)

#### Motivation I do not like having to update the same information in two places #### Modification Add script to generate a README.md for all CLIs that are registered in the `AllCommands` Generate the READMEs on every push to master to validate they have not been modified. #### Checklist _If not applicable, provide explanation of why._ - [ ] Tests updated - [ ] Docs updated - [ ] Issue linked in Title
linz · Sep 22, 2024 · 249799a · 249799a
1 parent e28771d
commit 249799a
Showing 12 changed files with 406 additions and 32 deletions.
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
@@ -8,6 +8,15 @@ jobs:
         with:
           node-version: 20.x
 
+      - name: Generate Readme
+        run: |
+          node build/src/readme.generate.js
+
+      # Validate no READMEs have been updated
+      - name: Validate Readme generation
+        run: |
+          git diff --exit-code
+
       # Only build containers on branches otherwise container builds are duplicated deploy-nonprod-containers
       - name: Set up Docker Buildx
         if: ${{ github.ref != 'refs/heads/master' }}

diff --git a/src/commands/copy/README.md b/src/commands/copy/README.md
@@ -0,0 +1,32 @@
+# copy
+
+Copy a manifest of files
+
+## Usage
+
+copy <options> [...location]
+
+### Arguments
+
+| Usage         | Description              | Options |
+| ------------- | ------------------------ | ------- |
+| [...location] | Manifest of file to copy |         |
+
+### Options
+
+| Usage                  | Description                         | Options  |
+| ---------------------- | ----------------------------------- | -------- |
+| --config <str>         | Location of role configuration file | optional |
+| --concurrency <number> | a number                            | optional |
+
+### Flags
+
+| Usage              | Description                                                            | Options        |
+| ------------------ | ---------------------------------------------------------------------- | -------------- |
+| --verbose          | Verbose logging                                                        |                |
+| --force            | Overwrite existing files                                               | default: false |
+| --no-clobber       | Skip existing files                                                    | default: false |
+| --force-no-clobber | Overwrite changed files                                                | default: false |
+| --fix-content-type | Correct content-type from "application/octet-stream" to common formats | default: false |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/create-manifest/README.md b/src/commands/create-manifest/README.md
@@ -0,0 +1,36 @@
+# create-manifest
+
+Create a list of files to copy and pass as a manifest
+
+## Usage
+
+create-manifest <options> [...source]
+
+### Arguments
+
+| Usage       | Description   | Options |
+| ----------- | ------------- | ------- |
+| [...source] | Where to list |         |
+
+### Options
+
+| Usage              | Description                                             | Options  |
+| ------------------ | ------------------------------------------------------- | -------- |
+| --config <str>     | Location of role configuration file                     | optional |
+| --transform <str>  | Transform/rename files                                  | optional |
+| --include <str>    | Include files eg ".\*.tiff?$"                           | optional |
+| --exclude <str>    | Exclude files eg ".\*.prj$"                             | optional |
+| --group-size <str> | Group files into this size per group, eg "5Gi" or "3TB" | optional |
+| --group <number>   | Group files into this number per group                  | optional |
+| --limit <number>   | Limit the file count to this amount, -1 is no limit     | optional |
+| --output <str>     | Output location for the listing                         |          |
+| --target <str>     | Copy destination                                        |          |
+
+### Flags
+
+| Usage     | Description                              | Options |
+| --------- | ---------------------------------------- | ------- |
+| --verbose | Verbose logging                          |         |
+| --flatten | Flatten the files in the target location |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/group/README.md b/src/commands/group/README.md
@@ -0,0 +1,30 @@
+# group
+
+group a array of inputs into a set
+
+## Usage
+
+group <options> [...items]
+
+### Arguments
+
+| Usage      | Description                                 | Options |
+| ---------- | ------------------------------------------- | ------- |
+| [...items] | list of items to group, can be a JSON array |         |
+
+### Options
+
+| Usage             | Description                                         | Options     |
+| ----------------- | --------------------------------------------------- | ----------- |
+| --config <str>    | Location of role configuration file                 | optional    |
+| --size <number>   | Group items into this number of items group         | default: 50 |
+| --from-file <str> | JSON file to load inputs from, must be a JSON Array | optional    |
+
+### Flags
+
+| Usage          | Description                   | Options        |
+| -------------- | ----------------------------- | -------------- |
+| --verbose      | Verbose logging               |                |
+| --force-output | force output additional files | default: false |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/index.ts b/src/commands/index.ts
@@ -16,40 +16,42 @@ import { commandStacSync } from './stac-sync/stac.sync.js';
 import { commandStacValidate } from './stac-validate/stac.validate.js';
 import { commandTileIndexValidate } from './tileindex-validate/tileindex.validate.js';
 
+export const AllCommands = {
+  copy: commandCopy,
+  'create-manifest': commandCreateManifest,
+  group: commandGroup,
+  flatten: commandCreateManifest,
+  'lds-fetch-layer': commandLdsFetch,
+  list: commandList,
+  ls: commandList,
+  'stac-catalog': commandStacCatalog,
+  'stac-github-import': commandStacGithubImport,
+  'stac-sync': commandStacSync,
+  'stac-validate': commandStacValidate,
+  'tileindex-validate': commandTileIndexValidate,
+  stac: subcommands({
+    name: 'stac',
+    cmds: {
+      catalog: commandStacCatalog,
+      'github-import': commandStacGithubImport,
+      sync: commandStacSync,
+      validate: commandStacValidate,
+    },
+  }),
+  bmc: subcommands({
+    name: 'bmc',
+    cmds: {
+      'create-pr': basemapsCreatePullRequest,
+      'create-mapsheet': basemapsCreateMapSheet,
+    },
+  }),
+  'pretty-print': commandPrettyPrint,
+  'generate-path': commandGeneratePath,
+};
+
 export const cmd = subcommands({
   name: 'argo-tasks',
   version: CliInfo.version,
   description: 'Utility tasks for argo',
-  cmds: {
-    copy: commandCopy,
-    'create-manifest': commandCreateManifest,
-    group: commandGroup,
-    flatten: commandCreateManifest,
-    'lds-fetch-layer': commandLdsFetch,
-    list: commandList,
-    ls: commandList,
-    'stac-catalog': commandStacCatalog,
-    'stac-github-import': commandStacGithubImport,
-    'stac-sync': commandStacSync,
-    'stac-validate': commandStacValidate,
-    'tileindex-validate': commandTileIndexValidate,
-    stac: subcommands({
-      name: 'stac',
-      cmds: {
-        catalog: commandStacCatalog,
-        'github-import': commandStacGithubImport,
-        sync: commandStacSync,
-        validate: commandStacValidate,
-      },
-    }),
-    bmc: subcommands({
-      name: 'bmc',
-      cmds: {
-        'create-pr': basemapsCreatePullRequest,
-        'create-mapsheet': basemapsCreateMapSheet,
-      },
-    }),
-    'pretty-print': commandPrettyPrint,
-    'generate-path': commandGeneratePath,
-  },
+  cmds: AllCommands,
 });
diff --git a/src/commands/list/README.md b/src/commands/list/README.md
@@ -0,0 +1,33 @@
+# list
+
+List and group files into collections of tasks
+
+## Usage
+
+list <options> [...location]
+
+### Arguments
+
+| Usage         | Description   | Options |
+| ------------- | ------------- | ------- |
+| [...location] | Where to list |         |
+
+### Options
+
+| Usage              | Description                                             | Options  |
+| ------------------ | ------------------------------------------------------- | -------- |
+| --config <str>     | Location of role configuration file                     | optional |
+| --include <str>    | Include files eg ".\*.tiff?$"                           | optional |
+| --exclude <str>    | Exclude files eg ".\*.prj$"                             | optional |
+| --group-size <str> | Group files into this size per group, eg "5Gi" or "3TB" | optional |
+| --group <number>   | Group files into this number per group                  | optional |
+| --limit <number>   | Limit the file count to this amount, -1 is no limit     | optional |
+| --output <str>     | Output location for the listing                         | optional |
+
+### Flags
+
+| Usage     | Description     | Options |
+| --------- | --------------- | ------- |
+| --verbose | Verbose logging |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/stac-catalog/README.md b/src/commands/stac-catalog/README.md
@@ -0,0 +1,29 @@
+# stac-catalog
+
+Construct STAC catalog
+
+## Usage
+
+stac-catalog <options> <str>
+
+### Arguments
+
+| Usage | Description                                  | Options |
+| ----- | -------------------------------------------- | ------- |
+| <str> | Location to search for collection.json paths |         |
+
+### Options
+
+| Usage            | Description                                          | Options  |
+| ---------------- | ---------------------------------------------------- | -------- |
+| --config <str>   | Location of role configuration file                  | optional |
+| --template <str> | JSON template file location for the Catalog metadata |          |
+| --output <str>   | Output location for the catalog                      |          |
+
+### Flags
+
+| Usage     | Description     | Options |
+| --------- | --------------- | ------- |
+| --verbose | Verbose logging |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/stac-github-import/README.md b/src/commands/stac-github-import/README.md
@@ -0,0 +1,26 @@
+# stac-github-import
+
+Format and push a STAC collection.json file and Argo Workflows parameters file to a GitHub repository
+
+## Usage
+
+stac-github-import <options>
+
+### Options
+
+| Usage                 | Description                                            | Options               |
+| --------------------- | ------------------------------------------------------ | --------------------- |
+| --config <str>        | Location of role configuration file                    | optional              |
+| --source <value>      | Source location of the collection.json file            |                       |
+| --target <value>      | Target location for the collection.json file           |                       |
+| --repo-name <value>   | One of 'linz/elevation', 'linz/imagery'                | default: linz/imagery |
+| --copy-option <value> | One of '--force', '--no-clobber', '--force-no-clobber' | default: --no-clobber |
+| --ticket <str>        | Associated JIRA ticket e.g. AIP-74                     | default:              |
+
+### Flags
+
+| Usage     | Description     | Options |
+| --------- | --------------- | ------- |
+| --verbose | Verbose logging |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/stac-sync/README.md b/src/commands/stac-sync/README.md
@@ -0,0 +1,28 @@
+# stac-sync
+
+Sync STAC files
+
+## Usage
+
+stac-sync <options> <str> <arg>
+
+### Arguments
+
+| Usage | Description                                              | Options |
+| ----- | -------------------------------------------------------- | ------- |
+| <str> | Location of the source STAC to synchronise from          |         |
+| <arg> | Location of the destination STAC in S3 to synchronise to |         |
+
+### Options
+
+| Usage          | Description                         | Options  |
+| -------------- | ----------------------------------- | -------- |
+| --config <str> | Location of role configuration file | optional |
+
+### Flags
+
+| Usage     | Description     | Options |
+| --------- | --------------- | ------- |
+| --verbose | Verbose logging |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/stac-validate/README.md b/src/commands/stac-validate/README.md
@@ -0,0 +1,32 @@
+# stac-validate
+
+Validate STAC files
+
+## Usage
+
+stac-validate <options> [...location]
+
+### Arguments
+
+| Usage         | Description                            | Options |
+| ------------- | -------------------------------------- | ------- |
+| [...location] | Location of the STAC files to validate |         |
+
+### Options
+
+| Usage                  | Description                            | Options  |
+| ---------------------- | -------------------------------------- | -------- |
+| --config <str>         | Location of role configuration file    | optional |
+| --concurrency <number> | Number of requests to run concurrently | optional |
+
+### Flags
+
+| Usage             | Description                                               | Options |
+| ----------------- | --------------------------------------------------------- | ------- |
+| --verbose         | Verbose logging                                           |         |
+| --checksum-assets | Validate the file:checksum of each asset if it exists     |         |
+| --checksum-links  | Validate the file:checksum of each STAC link if it exists |         |
+| --recursive       | Follow and validate STAC links                            |         |
+| --strict          | Strict checking                                           |         |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->
diff --git a/src/commands/tileindex-validate/README.md b/src/commands/tileindex-validate/README.md
@@ -0,0 +1,34 @@
+# tileindex-validate
+
+List input files and validate there are no duplicates.
+
+## Usage
+
+tileindex-validate <options> [...location]
+
+### Arguments
+
+| Usage         | Description                  | Options |
+| ------------- | ---------------------------- | ------- |
+| [...location] | Location of the source files |         |
+
+### Options
+
+| Usage                  | Description                                          | Options       |
+| ---------------------- | ---------------------------------------------------- | ------------- |
+| --config <str>         | Location of role configuration file                  | optional      |
+| --include <str>        | Include files eg ".\*.tiff?$"                        | optional      |
+| --scale <value>        | Tile grid scale to align output tile to              |               |
+| --source-epsg <number> | Force epsg code for input tiffs                      | optional      |
+| --preset <str>         | Validate the input tiffs with a configuration preset | default: none |
+
+### Flags
+
+| Usage          | Description                                                | Options        |
+| -------------- | ---------------------------------------------------------- | -------------- |
+| --verbose      | Verbose logging                                            |                |
+| --retile       | Output tile configuration for retiling                     | default: false |
+| --validate     | Validate that all input tiffs perfectly align to tile grid | default: true  |
+| --force-output | force output additional files                              | default: false |
+
+<!-- This file has been autogenerated by src/readme.generate.ts -->