feat: add 'all' option to add all the documentation to the readme in …

…one go (#537)

* GH-240 upgrade packages to remove vulnerabilities

* GH-240 move test fixtures to folders to separate action and workflow tests

* GH-240 duplicate tests for workflows

* GH-420 add run scripts to run action/workflow manually and run tests for action/workflow separately

* WIP

* GH-240 update CONTRIBUTING where command does not work and add additional helper scripts

* GH-240 add option to have a top level header containing the name

* GH-240 add header to readme and tests

* Remove unused files

* GH-240 fix error with enum

* GH-240 ability to display workflow inputs and outputs

* GH-240 add usage

* GH-240 start adding workflow tests

* GH-240 get a few more workflow tests working

* Update action test files with main

* GH-240 fix test for readme

* GH-240 all fields readme test working

* GH-240 sort out renaming of action > workflow of test files

* GH-240 fix crlf test

* GH-240 all tests fixed

* GH-240 amend readme for workflow functionality

* GH-240 add back in new lines at end of files

* GH-240 tweak to readme to clarify description is only for actions

* Add 'all' option to add docs to readme

* Tidy up from merge

README.md

@@ -73,7 +73,7 @@ Options:
 
 ### 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`.
+Action-docs can update your README based on the `action.yml`. The following sections can be updated: name header, description, inputs, outputs, usage, and runs. Add the following tags to your README and run `action-docs -u`.
 
 ```md
 <!-- action-docs-header source="action.yml" -->
@@ -84,7 +84,15 @@ Action-docs can update your README based on the `action.yml`. The following sect
 
 <!-- action-docs-outputs source="action.yml" -->
 
-<!-- action-docs-runs source="action.yml" -->
+<!-- action-docs-runs action="action.yml" -->
+
+<!-- action-docs-usage action="action.yml" project="<project>" version="<version>" -->
+```
+
+Or to include all of the above, use:
+
+```md
+<!-- action-docs-all source="action.yml" project="<project>" version="<version>" -->
 ```
 
 For updating other Markdown files add the name of the file to the command `action-docs -u <file>`.

__tests__/action-docs-action.test.ts

@@ -87,6 +87,14 @@ describe("Test update readme ", () => {
     );
   });
 
+  test("All fields one annotation", async () => {
+    await testReadme({
+      sourceFile: path.join(fixtureDir, "all_fields_action.yml"),
+      originalReadme: path.join(fixtureDir, "all_fields_one_annotation.input"),
+      fixtureReadme: path.join(fixtureDir, "all_fields_one_annotation.output"),
+    });
+  });
+
   test("Filled readme (all fields)", async () => {
     await testReadme({
       sourceFile: path.join(fixtureDir, "all_fields_action.yml"),

__tests__/action-docs-workflow.test.ts

@@ -62,6 +62,14 @@ describe("Test update readme ", () => {
     });
   });
 
+  test("All fields one annotation", async () => {
+    await testReadme({
+      sourceFile: path.join(fixtureDir, "all_fields_workflow.yml"),
+      originalReadme: path.join(fixtureDir, "all_fields_one_annotation.input"),
+      fixtureReadme: path.join(fixtureDir, "all_fields_one_annotation.output"),
+    });
+  });
+
   test("Filled readme (all fields)", async () => {
     await testReadme({
       sourceFile: path.join(fixtureDir, "all_fields_workflow.yml"),

__tests__/fixtures/action/all_fields_one_annotation.input

@@ -0,0 +1 @@
+<!-- action-docs-all source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->

__tests__/fixtures/action/all_fields_one_annotation.output

@@ -0,0 +1,64 @@
+<!-- action-docs-all source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
+## Description
+
+Default test
+
+## Inputs
+
+| name | description | required | default |
+| --- | --- | --- | --- |
+| `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
+
+| name | description |
+| --- | --- |
+| `outputA` | <p>A description A</p> |
+| `outputB` | <p>A description B</p> |
+
+
+## Runs
+
+This action is a `node12` action.
+
+## Usage
+
+```yaml
+- uses: npalm/action-docs@v1
+  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
+```
+<!-- action-docs-all source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->

__tests__/fixtures/workflow/all_fields_one_annotation.input

@@ -0,0 +1 @@
+<!-- action-docs-all source="__tests__/fixtures/workflow/all_fields_workflow.yml" project="npalm/action-docs" version="v1" -->

__tests__/fixtures/workflow/all_fields_one_annotation.output

@@ -0,0 +1,65 @@
+<!-- action-docs-all source="__tests__/fixtures/workflow/all_fields_workflow.yml" project="npalm/action-docs" version="v1" -->
+## A Workflow
+
+### Inputs
+
+| name | description | type | required | default |
+| --- | --- | --- | --- | --- |
+| `inputA` | <p>A description A</p> | `string` | `false` | `""` |
+| `inputB` | <p>A description B</p> | `string` | `true` | `""` |
+| `inputC` | <p>A description C</p> | `string` | `true` | `C` |
+| `inputD` | <p>A description D</p> | `string` | `false` | `D` |
+| `inputE` | <p>A description E</p> | `string` | `false` | `false` |
+
+
+### Outputs
+
+| name | description |
+| --- | --- |
+| `outputA` | <p>A description A</p> |
+| `outputB` | <p>A description B</p> |
+
+
+### Usage
+
+```yaml
+jobs:
+  job1:
+    uses: npalm/action-docs@v1
+    with:
+      inputA:
+      # A description A
+      #
+      # Type: string
+      # Required: false
+      # Default: ""
+
+      inputB:
+      # A description B
+      #
+      # Type: string
+      # Required: true
+      # Default: ""
+
+      inputC:
+      # A description C
+      #
+      # Type: string
+      # Required: true
+      # Default: C
+
+      inputD:
+      # A description D
+      #
+      # Type: string
+      # Required: false
+      # Default: D
+
+      inputE:
+      # A description E
+      #
+      # Type: string
+      # Required: false
+      # Default: false
+```
+<!-- action-docs-all source="__tests__/fixtures/workflow/all_fields_workflow.yml" project="npalm/action-docs" version="v1" -->

src/action-docs.ts

@@ -209,6 +209,10 @@ export async function generateActionMarkdownDocs(
     outputString += value;
   }
 
+  if (options.updateReadme) {
+    await updateReadme(options, outputString, "all", options.sourceFile);
+  }
+
   return outputString;
 }
 
@@ -318,15 +322,15 @@ async function updateReadme(
   if (sourceOrActionMatches) {
     const sourceOrAction = sourceOrActionMatches[1];
 
-    if (section === "usage") {
+    if (section === "usage" || section === "all") {
       const match = readmeFileText.match(
         new RegExp(
-          `<!-- action-docs-usage ${sourceOrAction}="${escapeRegExp(sourceFile)}" project="(.*)" version="(.*)" -->.?`,
+          `<!-- action-docs-${section} ${sourceOrAction}="${escapeRegExp(sourceFile)}" project="(.*)" version="(.*)" -->.?`,
         ),
       ) as string[];
 
       if (match) {
-        const commentExpression = `<!-- action-docs-usage ${sourceOrAction}="${sourceFile}" project="${match[1]}" version="${match[2]}" -->`;
+        const commentExpression = `<!-- action-docs-${section} ${sourceOrAction}="${sourceFile}" project="${match[1]}" version="${match[2]}" -->`;
         const regexp = new RegExp(
           `${escapeRegExp(commentExpression)}(?:(?:\r\n|\r|\n.*)+${escapeRegExp(commentExpression)})?`,
         );