npalmGH-240 add usage

larmitage-bjss · Feb 14, 2024 · d55f6e5 · d55f6e5
1 parent ef810cc
commit d55f6e5
Show file tree

Hide file tree

Showing 5 changed files with 89 additions and 26 deletions.
diff --git a/__tests__/action-docs-action.test.ts b/__tests__/action-docs-action.test.ts
@@ -4,7 +4,7 @@ import * as path from "path";
 
 const fixtureDir = path.join("__tests__", "fixtures", "action");
 
-// By default an 'action.yml' is expected at the runtime location. Therefore we copy one during th test.
+// By default an 'action.yml' is expected at the runtime location. Therefore we copy one during the test.
 beforeAll(() => {
   copyFileSync(path.join(fixtureDir, "action.yml"), "action.yml");
 });

diff --git a/__tests__/action-docs-workflow.test.ts b/__tests__/action-docs-workflow.test.ts
@@ -4,7 +4,7 @@ import * as path from "path";
 
 const fixtureDir = path.join("__tests__", "fixtures", "workflow");
 
-// By default a 'workflow.yml' is expected at the runtime location. Therefore we copy one during th test.
+// By default a 'workflow.yml' is expected at the runtime location. Therefore we copy one during the test.
 beforeAll(() => {
   copyFileSync(path.join(fixtureDir, "workflow.yml"), "workflow.yml");
 });
@@ -26,7 +26,6 @@ describe("Test output", () => {
     );
 
     expect(markdown).toEqual(expected);
-    expect("").toEqual("");
   });
 
   //   test("A minimal action definition.", async () => {

diff --git a/__tests__/fixtures/workflow/default.output b/__tests__/fixtures/workflow/default.output
@@ -15,3 +15,32 @@
 | `outputA` | <p>This is output A</p> |
 
 
+### Usage
+
+```yaml
+jobs:
+  job1:
+    uses: ***PROJECT***@***VERSION***
+    with:
+      inputA:
+      # - Item 1
+      #     - foo, bar, baz
+      # - Item 2
+      #     - [github](https://github.com/)
+      #     - **blah**
+      # - Item 3
+      #
+      # Type: string
+      # Required: false
+      # Default: This is a default
+
+      inputB:
+      # This is a
+      # multiline description
+      #
+      # Type: number
+      # Required: true
+      # Default: ""
+```
+
+
diff --git a/jest.config.js b/jest.config.js
@@ -15,10 +15,10 @@ const config = {
   verbose: true,
   coverageThreshold: {
     global: {
-      statements: 90,
-      branches: 90,
-      functions: 90,
-      lines: 90,
+      statements: 100,
+      branches: 97.14,
+      functions: 95.23,
+      lines: 100,
     },
   },
 };

diff --git a/src/action-docs.ts b/src/action-docs.ts
@@ -117,27 +117,53 @@ function createMdTable(
 function createMdCodeBlock(
   data: ActionInputsOutputs,
   options: DefaultOptions,
+  isAction = true,
 ): string {
   let codeBlockArray = ["```yaml"];
-  codeBlockArray.push(`- uses: ***PROJECT***@***VERSION***`);
-  codeBlockArray.push("  with:");
 
-  const inputs = getInputOutput(data, InputOutputType.actionInput, false);
+  let indent = "";
+
+  if (isAction) {
+    codeBlockArray.push(`- uses: ***PROJECT***@***VERSION***`);
+    indent += "  ";
+  } else {
+    codeBlockArray.push(`jobs:`);
+    indent += "  ";
+    codeBlockArray.push(`${indent}job1:`);
+    indent += "  ";
+    codeBlockArray.push(`${indent}uses: ***PROJECT***@***VERSION***`);
+  }
+
+  codeBlockArray.push(`${indent}with:`);
+  indent += "  ";
+
+  const inputs = getInputOutput(
+    data,
+    isAction ? InputOutputType.actionInput : InputOutputType.workflowInput,
+    false,
+  );
   for (const row of inputs.rows) {
-    const inputBlock = [`${row[0]}:`];
-    inputBlock.push(
-      ...row[1]
-        .split(/(\r\n|\n|\r)/gm)
-        .filter((l) => !["", "\r", "\n", "\r\n"].includes(l))
-        .map((l) => `# ${l}`),
-    );
+    const inputName = row[0];
+    const inputDescCommented = row[1]
+      .split(/(\r\n|\n|\r)/gm)
+      .filter((l) => !["", "\r", "\n", "\r\n"].includes(l))
+      .map((l) => `# ${l}`);
+    const type = isAction ? undefined : row[2];
+    const isRequired = isAction ? row[2] : row[3];
+    const defaultVal = isAction ? row[3] : row[4];
+
+    const inputBlock = [`${inputName}:`];
+    inputBlock.push(...inputDescCommented);
     inputBlock.push(`#`);
-    inputBlock.push(`# Required: ${row[2]}`); //.replace(/`/g, "")
-    if (row[3]) {
-      inputBlock.push(`# Default: ${row[3]}`);
+    if (type) {
+      inputBlock.push(`# Type: ${type}`);
+    }
+    inputBlock.push(`# Required: ${isRequired}`);
+    if (defaultVal) {
+      inputBlock.push(`# Default: ${defaultVal}`);
     }
 
-    codeBlockArray.push(...inputBlock.map((l) => `    ${l}`));
+    codeBlockArray.push(...inputBlock.map((l) => `${indent}${l}`));
     codeBlockArray.push("");
   }
   if (inputs.rows.length > 0) {
@@ -211,7 +237,7 @@ function generateActionDocs(
       `This action is a \`${yml.runs.using}\` action.`,
       "Runs",
     ),
-    usage: generateUsage(yml, options),
+    usage: generateUsage(yml.inputs, options),
   };
 }
 
@@ -228,7 +254,7 @@ function generateWorkflowDocs(
     ),
     outputs: generateOutputs(yml.on.workflow_call.outputs, options),
     runs: "",
-    usage: "", // todo
+    usage: generateUsage(yml.on.workflow_call.inputs, options, false),
   };
 }
 
@@ -263,8 +289,12 @@ function generateOutputs(
   return createMarkdownSection(options, outputMdTable, "Outputs");
 }
 
-function generateUsage(yml: ActionYml, options: DefaultOptions): string {
-  const usageMdCodeBlock = createMdCodeBlock(yml.inputs, options);
+function generateUsage(
+  data: ActionInputsOutputs,
+  options: DefaultOptions,
+  isAction = true,
+): string {
+  const usageMdCodeBlock = createMdCodeBlock(data, options, isAction);
   return createMarkdownSection(options, usageMdCodeBlock, "Usage");
 }
 
@@ -318,7 +348,12 @@ async function updateReadme(
     await replaceInFile.replaceInFile({
       files: options.readmeFile,
       from: regexp,
-      to: `${commentExpression}${lineBreak}${text.trim()}${lineBreak}${commentExpression}`,
+      to:
+        commentExpression +
+        lineBreak +
+        text.trim() +
+        lineBreak +
+        commentExpression,
     });
   }
 }