feat: annotate commands with examples (#1097)

#### Motivation

Storing examples with the code makes it easier to update the examples at
the same time the code is updated

#### Modification

Annotate commands with a examples in markdown

#### Checklist

_If not applicable, provide explanation of why._

- [ ] Tests updated
- [ ] Docs updated
- [ ] Issue linked in Title

.github/workflows/push.yml

@@ -10,7 +10,7 @@ jobs:
 
       - name: Generate Readme
         run: |
-          node build/src/readme.generate.js
+          node build/src/readme/readme.generate.js
 
       # Validate no READMEs have been updated
       - name: Validate Readme generation

README.md

@@ -209,15 +209,7 @@ stac github-import --source=SOURCE_S3_URL --target=TARGET_S3_URL [--repo-name=OW
 stac github-import --source=s3://linz-workflows-scratch/2024-03/13-is-niwe-hawkes-bay-all-blocks-xfcxl/flat/ --target=s3://nz-imagery/hawkes-bay/hawkes-bay_2023-2024_0.25m/rgb/2193/ --repo-name=linz/imagery-test --ticket=AIP-56 --copy-option=--force
 ```
 
-### `stac sync`
 
-Synchronise STAC (JSON) files from one path to another.
-
-#### Example
-
-```bash
-stac sync /path/to/stac/ s3://linz-imagery/
-```
 
 ### `stac validate`
 

src/commands/copy/README.md

@@ -29,4 +29,4 @@ copy <options> [...location]
 | --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 -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/create-manifest/README.md

@@ -33,4 +33,4 @@ create-manifest <options> [...source]
 | --verbose | Verbose logging                          |         |
 | --flatten | Flatten the files in the target location |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/generate-path/README.md

@@ -26,4 +26,4 @@ generate-path <options> <path>
 | --verbose                | Verbose logging                            |                |
 | --no-date-in-survey-path | Do not include the date in the survey path | default: false |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/group/README.md

@@ -27,4 +27,4 @@ group <options> [...items]
 | --verbose      | Verbose logging               |                |
 | --force-output | force output additional files | default: false |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/lds-fetch-layer/README.md

@@ -25,4 +25,4 @@ lds-fetch-layer <options> [...str]
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/list/README.md

@@ -30,4 +30,4 @@ list <options> [...location]
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/mapsheet-coverage/README.md

@@ -23,4 +23,4 @@ mapsheet-coverage <options>
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/pretty-print/README.md

@@ -25,4 +25,4 @@ pretty-print <options> <path>
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/stac-catalog/README.md

@@ -26,4 +26,4 @@ stac-catalog <options> <str>
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/stac-github-import/README.md

@@ -23,4 +23,4 @@ stac-github-import <options>
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/stac-sync/README.md

@@ -6,6 +6,14 @@ Sync STAC files
 
 stac-sync <options> <str> <arg>
 
+## Examples
+
+#### Sync STAC to s3
+
+```bash
+stac sync /path/to/stac/ s3://nz-imagery/
+```
+
 ### Arguments
 
 | Usage | Description                                              | Options |
@@ -25,4 +33,4 @@ stac-sync <options> <str> <arg>
 | --------- | --------------- | ------- |
 | --verbose | Verbose logging |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/stac-sync/stac.sync.ts

@@ -4,6 +4,8 @@ import { command, positional, string, Type } from 'cmd-ts';
 
 import { CliInfo } from '../../cli.info.js';
 import { logger } from '../../log.js';
+import { md } from '../../readme/markdown.js';
+import { annotateExample } from '../../readme/readme.example.js';
 import { hashBuffer, HashKey } from '../../utils/hash.js';
 import { config, registerCli, verbose } from '../common.js';
 
@@ -36,6 +38,8 @@ export const commandStacSync = command({
   },
 });
 
+annotateExample(commandStacSync, 'Sync STAC to s3', md.code('bash', 'stac sync /path/to/stac/ s3://nz-imagery/'));
+
 /**
  * Synchronise STAC (JSON) files from a path to another.
  *

src/commands/stac-validate/README.md

@@ -29,4 +29,4 @@ stac-validate <options> [...location]
 | --recursive       | Follow and validate STAC links                            |         |
 | --strict          | Strict checking                                           |         |
 
-<!-- This file has been autogenerated by src/readme.generate.ts -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/commands/tileindex-validate/README.md

@@ -31,4 +31,4 @@ tileindex-validate <options> [...location]
 | --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 -->
+<!-- This file has been autogenerated by src/readme/readme.generate.ts -->

src/readme/markdown.ts

@@ -0,0 +1,16 @@
+export const md = {
+  /**
+   * Create a markdown code block
+   *
+   * @param body body of the code block
+   * @param lang language to use eg `bash`
+   * @returns markdown formatted code block
+   */
+  code(lang: 'bash' | 'typescript', body: string): string {
+    return `
+\`\`\`${lang}
+${body}
+\`\`\`
+`;
+  },
+};

src/readme/readme.example.ts

@@ -0,0 +1,39 @@
+export const ExampleSymbol = Symbol('example-text');
+
+export interface CommandWithExamples {
+  /**
+   * list of examples to be added to the command README.md
+   *
+   * @see {@link generateReadme} for README generation
+   */
+  [ExampleSymbol]: { title: string; text: string }[];
+}
+
+/**
+ * Annotate a command with examples
+ *
+ * @param cmd Command to annotate
+ * @param exampleTitle Title for the example
+ * @param exampleText body of the example, markdown is supported
+ */
+export function annotateExample(cmd: unknown, exampleTitle: string, exampleText: string): void {
+  if (cmd == null) throw new Error('Command is null');
+  const ce = cmd as CommandWithExamples;
+  const examples = ce[ExampleSymbol] ?? [];
+
+  examples.push({ title: exampleTitle, text: exampleText });
+  ce[ExampleSymbol] = examples;
+}
+
+/**
+ * Does the command have examples annotated
+ *
+ * @see {@link annotateExample}
+ *
+ * @param cmd
+ * @returns whether there are examples
+ */
+export function commandHasExample<T>(cmd: T): cmd is T & CommandWithExamples {
+  if (cmd == null) return false;
+  return (cmd as unknown as CommandWithExamples)[ExampleSymbol] != null;
+}

src/readme.generate.ts → src/readme/readme.generate.ts

@@ -3,7 +3,8 @@ import type { HelpTopic, ProvidesHelp } from 'cmd-ts/dist/cjs/helpdoc.js';
 import { writeFileSync } from 'fs';
 import * as prettier from 'prettier';
 
-import { AllCommands } from './commands/index.js';
+import { AllCommands } from '../commands/index.js';
+import { commandHasExample, ExampleSymbol } from './readme.example.js';
 const AnsiRemove = /\u001b\[.*?m/g;
 
 function hasHelp(f: unknown): f is ProvidesHelp {
@@ -56,6 +57,16 @@ async function generateReadme(): Promise<void> {
     data.push();
     data.push(`${cmd.name} <options> ` + args.map((m) => m.usage).join(' '));
 
+    if (commandHasExample(cmd)) {
+      data.push();
+      data.push('## Examples');
+      for (const example of cmd[ExampleSymbol]) {
+        data.push(`#### ${example.title}`);
+        data.push();
+        data.push(example.text);
+      }
+    }
+
     for (const topics of [args, options, flags]) {
       const firstTopic = topics[0]?.category;
 
@@ -73,7 +84,7 @@ async function generateReadme(): Promise<void> {
       }
     }
     data.push();
-    data.push('<!-- This file has been autogenerated by src/readme.generate.ts -->');
+    data.push('<!-- This file has been autogenerated by src/readme/readme.generate.ts -->');
     data.push();
 
     const text = data.join('\n');