feat!: support multiple actions in a single readme (#505)

update - deps - tests - table format - use HTML for descriptions
npalm · Feb 4, 2024 · 284bf3f · 284bf3f
1 parent dc7fc53
commit 284bf3f
Show file tree

Hide file tree

Showing 31 changed files with 3,909 additions and 4,385 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -7,6 +7,11 @@
       "sourceType": "module",
       "project": "./tsconfig.json"
     },
+    "settings": {
+      "import/resolver": {
+        "typescript": {}
+      }
+    },
     "rules": {
       "no-console": "off",
       "eslint-comments/no-use": "off",

diff --git a/README.md b/README.md
@@ -12,23 +12,23 @@ A CLI to generate and update documentation for GitHub actions, based on the acti
 
 ### Add the following comment blocks to your README.md
 
-```
-<!-- action-docs-description -->
+```md
+<!-- action-docs-description action="action.yml" -->
 
-<!-- action-docs-inputs -->
+<!-- action-docs-inputs action="action.yml" -->
 
-<!-- action-docs-outputs -->
+<!-- action-docs-outputs action="action.yml" -->
 
-<!-- action-docs-runs -->
+<!-- action-docs-runs action="action.yml" -->
 ```
 
 Optionally you can also add the following section to generate a usage guide, replacing \<project\> and \<version\> with the name and version of your project you would like to appear in your usage guide.
 
-```
-<!-- action-docs-usage project="<project>" version="<version>" -->
+```md
+<!-- action-docs-usage action="action.yml" project="<project>" version="<version>" -->
 ```
 
-### Generate docs via CLI.
+### Generate docs via CLI
 
 ```bash
 npm install -g action-docs
@@ -69,18 +69,22 @@ Options:
 
 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`.
 
-```
-<!-- action-docs-description -->
+```md
+<!-- action-docs-description action="action.yml" -->
 
-<!-- action-docs-inputs -->
+<!-- action-docs-inputs action="action.yml" -->
 
-<!-- action-docs-outputs -->
+<!-- action-docs-outputs action="action.yml" -->
 
-<!-- action-docs-runs -->
+<!-- action-docs-runs action="action.yml" -->
 ```
 
 For updating other Markdown files add the name of the file to the command `action-docs -u <file>`.
 
+If you need to use `another/action.yml`:
+
+1. write it in tags like `action="another/action.yml"`;
+1. specify in a command via the `-a` option like `action-docs -a another/action.yml`
 
 ### Examples
 
@@ -96,11 +100,10 @@ action-docs
 action-docs --update-readme
 ```
 
-
 #### Print action markdown for non default action file
 
 ```bash
-action-docs --action ./action.yaml
+action-docs --action another/action.yaml
 ```
 
 #### Update readme, custom action file and set TOC level 3, custom readme
@@ -109,9 +112,6 @@ action-docs --action ./action.yaml
 action-docs --action ./some-dir/action.yml --toc-level 3 --update-readme docs.md
 ```
 
-
-
-
 ## API
 
 ```javascript
@@ -127,8 +127,7 @@ await generateActionMarkdownDocs({
 
 ## Contribution
 
-We welcome contributions, please checkout the [contribution guide](CONTRIBUTING.md). 
-
+We welcome contributions, please checkout the [contribution guide](CONTRIBUTING.md).
 
 ## License
 

diff --git a/__tests__/action-docs.test.ts b/__tests__/action-docs.test.ts
@@ -1,7 +1,6 @@
 import { generateActionMarkdownDocs, Options } from "../src";
-import { readFileSync, writeFileSync, copyFileSync, rmSync, unlink } from "fs";
+import { readFileSync, writeFileSync, copyFileSync, unlink } from "fs";
 import * as path from "path";
-import { option } from "yargs";
 
 const fixtureDir = path.join("__tests__", "fixtures");
 
@@ -73,9 +72,35 @@ describe("Test update readme ", () => {
         originalReadme: path.join(fixtureDir, "all_fields_readme.input.crlf"),
         fixtureReadme: path.join(fixtureDir, "all_fields_readme.output.crlf"),
       },
-      { lineBreaks: "CRLF" }
+      { lineBreaks: "CRLF" },
     );
   });
+
+  test("Readme (inputs) for action-docs-action", async () => {
+    await testReadme({
+      actionFile: path.join(fixtureDir, "action_docs_action_action.yml"),
+      originalReadme: path.join(fixtureDir, "action_docs_action_readme.input"),
+      fixtureReadme: path.join(fixtureDir, "action_docs_action_readme.output"),
+    });
+  });
+
+  test("Readme for two action.yml-s", async () => {
+    await testReadme(
+      {
+        actionFile: path.join(fixtureDir, "action_docs_action_action.yml"),
+        originalReadme: path.join(fixtureDir, "two_actions_readme.input"),
+        fixtureReadme: path.join(fixtureDir, "two_actions_readme.output"),
+      },
+      {},
+      false,
+    );
+
+    await testReadme({
+      actionFile: path.join(fixtureDir, "all_fields_action.yml"),
+      originalReadme: path.join(fixtureDir, "two_actions_readme.input"),
+      fixtureReadme: path.join(fixtureDir, "two_actions_readme.output"),
+    });
+  });
 });
 
 describe("Test usage format", () => {
@@ -104,7 +129,8 @@ interface ReadmeTestFixtures {
 
 async function testReadme(
   files: ReadmeTestFixtures,
-  overwriteOptions?: Options
+  overwriteOptions?: Options,
+  doExpect: boolean = true,
 ) {
   const expected = <string>readFileSync(files.fixtureReadme, "utf-8");
   const original = <string>readFileSync(files.originalReadme, "utf-8");
@@ -118,6 +144,8 @@ async function testReadme(
 
   const updated = <string>readFileSync(files.originalReadme, "utf-8");
 
-  writeFileSync(files.originalReadme, original);
-  expect(updated).toEqual(expected);
+  if (doExpect) {
+    writeFileSync(files.originalReadme, original);
+    expect(updated).toEqual(expected);
+  }
 }
diff --git a/__tests__/cli.test.ts b/__tests__/cli.test.ts
@@ -10,7 +10,7 @@ describe("CLI tests", () => {
     await testReadme(
       path.join(fixtureDir, "all_fields_action.yml"),
       path.join(fixtureDir, "all_fields_readme.input"),
-      path.join(fixtureDir, "all_fields_readme.output")
+      path.join(fixtureDir, "all_fields_readme.output"),
     );
   });
 
@@ -19,19 +19,19 @@ describe("CLI tests", () => {
       path.join(fixtureDir, "all_fields_action.yml.crlf"),
       path.join(fixtureDir, "all_fields_readme.input.crlf"),
       path.join(fixtureDir, "all_fields_readme.output.crlf"),
-      "-l CRLF"
+      "-l CRLF",
     );
   });
 
   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 __tests__/fixtures/all_fields_action.yml -t 3 --no-banner`,
     );
 
     const expected = <string>(
       readFileSync(
         path.join(fixtureDir, "all_fields_action_toc3_cli.output"),
-        "utf-8"
+        "utf-8",
       )
     );
 
@@ -50,15 +50,15 @@ interface CliRespone {
 function cli(args: string): Promise<CliRespone> {
   return new Promise((resolve) => {
     cp.exec(
-      `ts-node ${path.resolve("src/cli.ts")} ${args}`,
+      `node ${path.resolve("lib/cli.js")} ${args}`,
       (error, stdout, stderr) => {
         resolve({
           code: error && error.code ? error.code : 0,
           error,
           stdout,
           stderr,
         });
-      }
+      },
     );
   });
 }
@@ -68,13 +68,13 @@ async function testReadme(
   originalReadme: string,
   fixtureReadme: string,
   extraArgs = "",
-  exitCode = 0
+  exitCode = 0,
 ) {
   const expected = <string>readFileSync(fixtureReadme, "utf-8");
   const original = <string>readFileSync(originalReadme, "utf-8");
 
   const result = await cli(
-    `-u ${originalReadme} -a ${actionFile} ${extraArgs}`
+    `-u ${originalReadme} -a ${actionFile} ${extraArgs}`,
   );
   expect(result.code).toBe(exitCode);
 

diff --git a/__tests__/fixtures/action.yml b/__tests__/fixtures/action.yml
@@ -5,8 +5,12 @@ inputs:
   inputA:
     required: false
     description: |
-      A description
-      This is a multiline description
+      - Item 1
+          - foo, bar, baz
+      - Item 2
+          - [github](https://github.com/)
+          - **blah**
+      - Item 3
     default: test
   inputB:
     required: false

diff --git a/__tests__/fixtures/action_docs_action_action.yml b/__tests__/fixtures/action_docs_action_action.yml
@@ -0,0 +1,29 @@
+name: 'Action update docs action'
+description: 'Action updates the action documentation.'
+author: 'Niek Palm'
+
+branding:
+  icon: book-open
+  color: purple
+
+inputs:
+  readme:
+    description: 'Readme file to update.'
+    required: false
+    default: README.md
+  actionFile: 
+    description: 'The action definition file.'
+    required: false
+    default: action.yml
+  tocLevel:
+    description: "TOC level used for the headers."
+    required: false
+    default: 2
+  lineBreaks:
+    description: "Line breaks to be used in updated readme (LF|CR|CRLF)."
+    required: false
+    default: LF
+
+runs:
+  using: 'node16'
+  main: 'dist/index.js'
diff --git a/__tests__/fixtures/action_docs_action_readme.input b/__tests__/fixtures/action_docs_action_readme.input
@@ -0,0 +1 @@
+<!-- action-docs-inputs action="__tests__/fixtures/action_docs_action_action.yml" -->
diff --git a/__tests__/fixtures/action_docs_action_readme.output b/__tests__/fixtures/action_docs_action_readme.output
@@ -0,0 +1,10 @@
+<!-- action-docs-inputs action="__tests__/fixtures/action_docs_action_action.yml" -->
+## Inputs
+
+| name | description | required | default |
+| --- | --- | --- | --- |
+| `readme` | <p>Readme file to update.</p> | `false` | `README.md` |
+| `actionFile` | <p>The action definition file.</p> | `false` | `action.yml` |
+| `tocLevel` | <p>TOC level used for the headers.</p> | `false` | `2` |
+| `lineBreaks` | <p>Line breaks to be used in updated readme (LF|CR|CRLF).</p> | `false` | `LF` |
+<!-- action-docs-inputs action="__tests__/fixtures/action_docs_action_action.yml" -->
diff --git a/__tests__/fixtures/action_usage_readme.input b/__tests__/fixtures/action_usage_readme.input
@@ -1 +1 @@
-<!-- action-docs-usage project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage action="__tests__/fixtures/action.yml" project="npalm/action-docs" version="v1" -->
diff --git a/__tests__/fixtures/action_usage_readme.output b/__tests__/fixtures/action_usage_readme.output
@@ -1,12 +1,16 @@
-<!-- action-docs-usage project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage action="__tests__/fixtures/action.yml" project="npalm/action-docs" version="v1" -->
 ## Usage
 
 ```yaml
 - uses: npalm/action-docs@v1
   with:
     inputA:
-    # A description
-    # This is a multiline description
+    # - Item 1
+    #     - foo, bar, baz
+    # - Item 2
+    #     - [github](https://github.com/)
+    #     - **blah**
+    # - Item 3
     #
     # Required: false
     # Default: test
@@ -18,4 +22,4 @@
     # Required: false
     # Default: test
 ```
-<!-- action-docs-usage project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage action="__tests__/fixtures/action.yml" project="npalm/action-docs" version="v1" -->
diff --git a/__tests__/fixtures/all_fields_action.output b/__tests__/fixtures/all_fields_action.output
@@ -4,21 +4,21 @@ Default test
 
 ## Inputs
 
-| parameter | description | required | default |
+| name | description | required | default |
 | --- | --- | --- | --- |
-| inputA | A description A | `false` |  |
-| inputB | A description B | `true` |  |
-| inputC | A description C | `true` | C |
-| inputD | A description D | `false` | D |
-| inputE | A description E | `false` | false |
+| `inputA` | <p>A description A</p> | `false` | `""` |
+| `inputB` | <p>A description B</p> | `true` | `""` |
+| `inputC` | <p>A description C</p> | `true` | `C` |
+| `inputD` | <p>A description D</p> | `false` | `D` |
+| `inputE` | <p>A description E</p> | `false` | `false` |
 
 
 ## Outputs
 
-| parameter | description |
+| name | description |
 | --- | --- |
-| outputA | A description A |
-| outputB | A description B |
+| `outputA` | <p>A description A</p> |
+| `outputB` | <p>A description B</p> |
 
 
 ## Runs

diff --git a/__tests__/fixtures/all_fields_action_toc1.output b/__tests__/fixtures/all_fields_action_toc1.output
@@ -2,23 +2,22 @@
 
 Default test
 
-# Inputs
+## Inputs
 
-| parameter | description | required | default |
+| name | description | required | default |
 | --- | --- | --- | --- |
-| inputA | A description A | `false` |  |
-| inputB | A description B | `true` |  |
-| inputC | A description C | `true` | C |
-| inputD | A description D | `false` | D |
-| inputE | A description E | `false` | false |
-
+| <p><code>inputA</code></p> | <p>A description A</p> | <p><code>false</code></p> | <p><code>""</code></p> |
+| <p><code>inputB</code></p> | <p>A description B</p> | <p><code>true</code></p> | <p><code>""</code></p> |
+| <p><code>inputC</code></p> | <p>A description C</p> | <p><code>true</code></p> | <p><code>C</code></p> |
+| <p><code>inputD</code></p> | <p>A description D</p> | <p><code>false</code></p> | <p><code>D</code></p> |
+| <p><code>inputE</code></p> | <p>A description E</p> | <p><code>false</code></p> | <p><code>false</code></p> |
 
 # Outputs
 
-| parameter | description |
+| name | description |
 | --- | --- |
-| outputA | A description A |
-| outputB | A description B |
+| `outputA` | <p>A description A</p> |
+| `outputB` | <p>A description B</p> |
 
 
 # Runs