WIP

npalm · Feb 13, 2024 · 5147c56 · 5147c56
1 parent b6cc7dc
commit 5147c56
Show file tree

Hide file tree

Showing 16 changed files with 15,664 additions and 1,101 deletions.
diff --git a/.tool-versions b/.tool-versions
@@ -0,0 +1 @@
+nodejs 20.11.0
diff --git a/README.md b/README.md
@@ -55,21 +55,24 @@ The following options are available via the CLI
 
 ```
 Options:
-      --help           Show help                                       [boolean]
-      --version        Show version number                             [boolean]
-  -t, --toc-level      TOC level used for markdown         [number] [default: 2]
-  -a, --action         GitHub action file       [string] [default: "action.yml"]
-      --no-banner      Print no banner
-  -u, --update-readme  Update readme file.                              [string]
-  -l, --line-breaks    Used line breaks in the generated docs.
-                          [string] [choices: "CR", "LF", "CRLF"] [default: "LF"]
+      --help                  Show help                                       [boolean]
+      --version               Show version number                             [boolean]
+  -t, --toc-level             TOC level used for markdown         [number] [default: 2]
+  -a, --action                GitHub action file       [string] [default: "action.yml"]
+      --no-banner             Print no banner
+  -u, --update-readme         Update readme file.                              [string]
+  -l, --line-breaks           Used line breaks in the generated docs.
+                                 [string] [choices: "CR", "LF", "CRLF"] [default: "LF"]
+  -h, --include-name-header   Include a header with the action/workflow name.
 ```
 
 ### Update the README
 
 Action-docs can update your README based on the `action.yml`. The following sections can be updated: description, inputs, outputs and runs. Add the following tags to your README and run `action-docs -u`.
 
 ```md
+<!-- action-docs-header action="action.yml" -->
+
 <!-- action-docs-description action="action.yml" -->
 
 <!-- action-docs-inputs action="action.yml" -->

diff --git a/__tests__/action-docs-workflow.test.ts b/__tests__/action-docs-workflow.test.ts
@@ -17,14 +17,15 @@ afterAll(() => {
 
 describe("Test output", () => {
   test("With defaults.", async () => {
-    // const markdown = await generateActionMarkdownDocs({
-    //   actionFile: path.join(fixtureDir, "workflow.yml"),
-    // });
-    // const expected = <string>(
-    //   readFileSync(path.join(fixtureDir, "default.output"), "utf-8")
-    // );
-
-    // expect(markdown).toEqual(expected);
+    const markdown = await generateActionMarkdownDocs({
+      actionFile: path.join(fixtureDir, "workflow.yml"),
+      includeNameHeader: true,
+    });
+    const expected = <string>(
+      readFileSync(path.join(fixtureDir, "default.output"), "utf-8")
+    );
+
+    expect(markdown).toEqual(expected);
     expect("").toEqual("");
   });
 

diff --git a/__tests__/cli.test.ts b/__tests__/cli.test.ts
@@ -3,7 +3,7 @@ import * as path from "path";
 
 import { readFileSync, writeFileSync } from "fs";
 
-const fixtureDir = path.join("__tests__", "fixtures");
+const fixtureDir = path.join("__tests__", "fixtures", "action");
 
 describe("CLI tests", () => {
   test("Update readme default", async () => {
@@ -25,7 +25,7 @@ describe("CLI tests", () => {
 
   test("Console output with TOC 3 and no banner.", async () => {
     const result = await cli(
-      `-a __tests__/fixtures/all_fields_action.yml -t 3 --no-banner`,
+      `-a ${path.join(fixtureDir, "all_fields_action.yml")} -t 3 --no-banner`,
     );
 
     const expected = <string>(
@@ -38,6 +38,19 @@ describe("CLI tests", () => {
     expect(result.code).toBe(0);
     expect(result.stdout).toEqual(`${expected}\n`);
   });
+
+  test("Console output including name header and no banner.", async () => {
+    const result = await cli(
+      `-a ${path.join(fixtureDir, "action.yml")} -h true --no-banner`,
+    );
+
+    const expected = <string>(
+      readFileSync(path.join(fixtureDir, "default-with-header.output"), "utf-8")
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toEqual(`${expected}\n`);
+  });
 });
 
 interface CliRespone {

diff --git a/__tests__/fixtures/action/all_fields_action.output b/__tests__/fixtures/action/all_fields_action.output
@@ -25,3 +25,40 @@ Default test
 
 This action is a `node12` action.
 
+## Usage
+
+```yaml
+- uses: ***PROJECT***@***VERSION***
+  with:
+    inputA:
+    # A description A
+    #
+    # Required: false
+    # Default: ""
+
+    inputB:
+    # A description B
+    #
+    # Required: true
+    # Default: ""
+
+    inputC:
+    # A description C
+    #
+    # Required: true
+    # Default: C
+
+    inputD:
+    # A description D
+    #
+    # Required: false
+    # Default: D
+
+    inputE:
+    # A description E
+    #
+    # Required: false
+    # Default: false
+```
+
+
diff --git a/__tests__/fixtures/action/all_fields_action_toc3_cli.output b/__tests__/fixtures/action/all_fields_action_toc3_cli.output
@@ -25,3 +25,40 @@ Default test
 
 This action is a `node12` action.
 
+### Usage
+
+```yaml
+- uses: ***PROJECT***@***VERSION***
+  with:
+    inputA:
+    # A description A
+    #
+    # Required: false
+    # Default: ""
+
+    inputB:
+    # A description B
+    #
+    # Required: true
+    # Default: ""
+
+    inputC:
+    # A description C
+    #
+    # Required: true
+    # Default: C
+
+    inputD:
+    # A description D
+    #
+    # Required: false
+    # Default: D
+
+    inputE:
+    # A description E
+    #
+    # Required: false
+    # Default: false
+```
+
+
diff --git a/__tests__/fixtures/action/default-with-header.output b/__tests__/fixtures/action/default-with-header.output
@@ -0,0 +1,50 @@
+## An Action
+
+### Description
+
+Default test
+
+### Inputs
+
+| name | description | required | default |
+| --- | --- | --- | --- |
+| `inputA` | <ul> <li>Item 1<ul> <li>foo, bar, baz</li></ul></li> <li>Item 2<ul> <li><a href="https://github.com/">github</a></li> <li><strong>blah</strong></li></ul></li> <li>Item 3</li> </ul> | `false` | `test` |
+| `inputB` | <p>This is a multiline description</p> | `false` | `test` |
+
+
+### Outputs
+
+| name | description |
+| --- | --- |
+| `outputA` | <p>A description</p> |
+
+
+### Runs
+
+This action is a `node12` action.
+
+### Usage
+
+```yaml
+- uses: ***PROJECT***@***VERSION***
+  with:
+    inputA:
+    # - Item 1
+    #     - foo, bar, baz
+    # - Item 2
+    #     - [github](https://github.com/)
+    #     - **blah**
+    # - Item 3
+    #
+    # Required: false
+    # Default: test
+
+    inputB:
+    # This is a
+    # multiline description
+    #
+    # Required: false
+    # Default: test
+```
+
+
diff --git a/__tests__/fixtures/action/default.output b/__tests__/fixtures/action/default.output
@@ -21,3 +21,28 @@ Default test
 
 This action is a `node12` action.
 
+## Usage
+
+```yaml
+- uses: ***PROJECT***@***VERSION***
+  with:
+    inputA:
+    # - Item 1
+    #     - foo, bar, baz
+    # - Item 2
+    #     - [github](https://github.com/)
+    #     - **blah**
+    # - Item 3
+    #
+    # Required: false
+    # Default: test
+
+    inputB:
+    # This is a
+    # multiline description
+    #
+    # Required: false
+    # Default: test
+```
+
+
diff --git a/__tests__/fixtures/action/minimal_action.output b/__tests__/fixtures/action/minimal_action.output
@@ -6,3 +6,11 @@ Default test
 
 This action is a `docker` action.
 
+## Usage
+
+```yaml
+- uses: ***PROJECT***@***VERSION***
+  with:
+```
+
+
diff --git a/__tests__/fixtures/workflow/default.output b/__tests__/fixtures/workflow/default.output
@@ -1,14 +1,14 @@
-# A Workflow
+## A Workflow
 
-## Inputs
+### Inputs
 
 | name | description | type | required | default |
 | --- | --- | --- | --- |
 | `inputA` | <ul> <li>Item 1<ul> <li>foo, bar, baz</li></ul></li> <li>Item 2<ul> <li><a href="https://github.com/">github</a></li> <li><strong>blah</strong></li></ul></li> <li>Item 3</li> </ul> | `string` | `false` | `This is a default` |
 | `inputB` | <p>This is a multiline description</p> | `number` | `true` |  |
 
 
-## Outputs
+### Outputs
 
 | name | description |
 | --- | --- |

diff --git a/jest.config.js b/jest.config.js
@@ -15,10 +15,10 @@ const config = {
   verbose: true,
   coverageThreshold: {
     global: {
-      statements: 100,
-      branches: 97.14,
-      functions: 95.23,
-      lines: 100,
+      statements: 90,
+      branches: 90,
+      functions: 90,
+      lines: 90,
     },
   },
 };