npalmGH-240 add source option and deprecate action option

CONTRIBUTING.md

@@ -80,15 +80,15 @@ Please provide tests for your contribution.
 To generate a new fixture for Markdown output run
 
 ```bash
-./lib/cli.js --no-banner -a __tests__/fixtures/<action>.yml | \ 
+./lib/cli.js --no-banner -s __tests__/fixtures/<action>.yml | \ 
   tail -r | tail -n +2 | tail -r > <action_md>.output
 ```
 
 For creating a README.md fixture, first create the readme input file for the test, and copy the same file to the an output file. Next run the following command to update the output which can be used to verify the test.
 
 
 ```bash
-./lib/cli.js --no-banner -a __tests__/fixtures/<action>.yml -u __tests_/fixtures/<readme>.output
+./lib/cli.js --no-banner -s __tests__/fixtures/<action>.yml -u __tests_/fixtures/<readme>.output
 ```
 
 ### Use a Consistent Coding Style

README.md

@@ -13,21 +13,21 @@ A CLI to generate and update documentation for GitHub actions or workflows, base
 ### Add the following comment blocks to your README.md
 
 ```md
-<!-- action-docs-header action="action.yml" -->
+<!-- action-docs-header source="action.yml" -->
 
-<!-- action-docs-description action="action.yml" --> # applicable for actions only
+<!-- action-docs-description source="action.yml" --> # applicable for actions only
 
-<!-- action-docs-inputs action="action.yml" -->
+<!-- action-docs-inputs source="action.yml" -->
 
-<!-- action-docs-outputs action="action.yml" -->
+<!-- action-docs-outputs source="action.yml" -->
 
-<!-- action-docs-runs action="action.yml" --> # applicable for actions only
+<!-- action-docs-runs source="action.yml" --> # applicable for actions only
 ```
 
 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.
 
 ```md
-<!-- action-docs-usage action="action.yml" project="<project>" version="<version>" -->
+<!-- action-docs-usage source="action.yml" project="<project>" version="<version>" -->
 ```
 
 ### Generate docs via CLI
@@ -57,39 +57,42 @@ 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"]
-  -n, --include-name-header   Include a header with the action/workflow name.
+      --version              Show version number                       [boolean]
+  -t, --toc-level            TOC level used for markdown   [number] [default: 2]
+  -a, --action               GitHub action file
+             [deprecated: use "source" instead] [string] [default: "action.yml"]
+  -s, --source               GitHub source 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"]
+  -n, --include-name-header  Include a header with the action/workflow name
+                                                                       [boolean]
+      --help                 Show help                                 [boolean]
 ```
 
 ### 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-header source="action.yml" -->
 
-<!-- action-docs-description action="action.yml" -->
+<!-- action-docs-description source="action.yml" -->
 
-<!-- action-docs-inputs action="action.yml" -->
+<!-- action-docs-inputs source="action.yml" -->
 
-<!-- action-docs-outputs action="action.yml" -->
+<!-- action-docs-outputs source="action.yml" -->
 
-<!-- action-docs-runs action="action.yml" -->
+<!-- action-docs-runs source="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`
+1. write it in tags like `source="another/action.yml"`;
+1. specify in a command via the `-s` option like `action-docs -s another/action.yml`
 
 ### Examples
 
@@ -108,13 +111,13 @@ action-docs --update-readme
 #### Print action markdown for non default action file
 
 ```bash
-action-docs --action another/action.yaml
+action-docs --source another/action.yaml
 ```
 
 #### Update readme, custom action file and set TOC level 3, custom readme
 
 ```bash
-action-docs --action ./some-dir/action.yml --toc-level 3 --update-readme docs.md
+action-docs --source ./some-dir/action.yml --toc-level 3 --update-readme docs.md
 ```
 
 ## API

__tests__/cli.test.ts

@@ -26,7 +26,7 @@ describe("CLI tests", () => {
 
   test("Console output with TOC 3 and no banner.", async () => {
     const result = await cli(
-      `-a ${path.join(fixtureDir, "all_fields_action.yml")} -t 3 --no-banner`,
+      `-s ${path.join(fixtureDir, "all_fields_action.yml")} -t 3 --no-banner`,
     );
 
     const expected = <string>(
@@ -42,7 +42,7 @@ describe("CLI tests", () => {
 
   test("Console output including name header and no banner.", async () => {
     const result = await cli(
-      `-a ${path.join(fixtureDir, "action.yml")} -n true --no-banner`,
+      `-s ${path.join(fixtureDir, "action.yml")} -n true --no-banner`,
     );
 
     const expected = <string>(
@@ -88,7 +88,7 @@ async function testReadme(
   const original = <string>readFileSync(originalReadme, "utf-8");
 
   const result = await cli(
-    `-u ${originalReadme} -a ${actionFile} ${extraArgs}`,
+    `-u ${originalReadme} -s ${actionFile} ${extraArgs}`,
   );
   expect(result.code).toBe(exitCode);
 

__tests__/fixtures/action/action_docs_action_readme.input

@@ -1 +1 @@
-<!-- action-docs-inputs action="__tests__/fixtures/action/action_docs_action_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/action_docs_action_action.yml" -->

__tests__/fixtures/action/action_docs_action_readme.output

@@ -1,4 +1,4 @@
-<!-- action-docs-inputs action="__tests__/fixtures/action/action_docs_action_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/action_docs_action_action.yml" -->
 ## Inputs
 
 | name | description | required | default |
@@ -7,4 +7,4 @@
 | `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/action_docs_action_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/action_docs_action_action.yml" -->

__tests__/fixtures/action/action_usage_readme.input

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

__tests__/fixtures/action/action_usage_readme.output

@@ -1,4 +1,4 @@
-<!-- action-docs-usage action="__tests__/fixtures/action/action.yml" project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage source="__tests__/fixtures/action/action.yml" project="npalm/action-docs" version="v1" -->
 ## Usage
 
 ```yaml
@@ -22,4 +22,4 @@
     # Required: false
     # Default: test
 ```
-<!-- action-docs-usage action="__tests__/fixtures/action/action.yml" project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage source="__tests__/fixtures/action/action.yml" project="npalm/action-docs" version="v1" -->

__tests__/fixtures/action/all_fields_readme.input

@@ -1,11 +1,11 @@
-<!-- action-docs-header action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-header source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-usage action="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->

__tests__/fixtures/action/all_fields_readme.input.crlf

@@ -1,7 +1,7 @@
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->

__tests__/fixtures/action/all_fields_readme.output

@@ -1,14 +1,14 @@
-<!-- action-docs-header action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-header source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## An Action
-<!-- action-docs-header action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-header source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 ### Description
 
 Default test
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-usage action="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
 ### Usage
 
 ```yaml
@@ -44,9 +44,9 @@ Default test
     # Required: false
     # Default: false
 ```
-<!-- action-docs-usage action="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
+<!-- action-docs-usage source="__tests__/fixtures/action/all_fields_action.yml" project="npalm/action-docs" version="v1" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ### Inputs
 
 | name | description | required | default |
@@ -56,19 +56,19 @@ Default test
 | `inputC` | <p>A description C</p> | `true` | `C` |
 | `inputD` | <p>A description D</p> | `false` | `D` |
 | `inputE` | <p>A description E</p> | `false` | `false` |
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ### Outputs
 
 | name | description |
 | --- | --- |
 | `outputA` | <p>A description A</p> |
 | `outputB` | <p>A description B</p> |
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ### Runs
 
 This action is a `node12` action.
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->

__tests__/fixtures/action/all_fields_readme.output.crlf

@@ -1,10 +1,10 @@
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 ## Description
 
 Default test
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 ## Inputs
 
 | name | description | required | default |
@@ -14,19 +14,19 @@ Default test
 | `inputC` | <p>A description C</p> | `true` | `C` |
 | `inputD` | <p>A description D</p> | `false` | `D` |
 | `inputE` | <p>A description E</p> | `false` | `false` |
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 ## Outputs
 
 | name | description |
 | --- | --- |
 | `outputA` | <p>A description A</p> |
 | `outputB` | <p>A description B</p> |
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
 ## Runs
 
 This action is a `node12` action.
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml.crlf" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml.crlf" -->

__tests__/fixtures/action/all_fields_readme_filled.input

@@ -1,12 +1,12 @@
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Description
 
 Default test
 
 
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Inputs
 
 | name | description | required | default |
@@ -19,9 +19,9 @@ Default test
 
 
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Outputs
 
 | name | description |
@@ -31,12 +31,12 @@ Default test
 
 
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Run
 
 This action is a `docker` action.
 
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->

__tests__/fixtures/action/all_fields_readme_filled.output

@@ -1,10 +1,10 @@
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Description
 
 Default test
-<!-- action-docs-description action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-description source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Inputs
 
 | name | description | required | default |
@@ -14,19 +14,19 @@ Default test
 | `inputC` | <p>A description C</p> | `true` | `C` |
 | `inputD` | <p>A description D</p> | `false` | `D` |
 | `inputE` | <p>A description E</p> | `false` | `false` |
-<!-- action-docs-inputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-inputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Outputs
 
 | name | description |
 | --- | --- |
 | `outputA` | <p>A description A</p> |
 | `outputB` | <p>A description B</p> |
-<!-- action-docs-outputs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-outputs source="__tests__/fixtures/action/all_fields_action.yml" -->
 
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->
 ## Runs
 
 This action is a `node12` action.
-<!-- action-docs-runs action="__tests__/fixtures/action/all_fields_action.yml" -->
+<!-- action-docs-runs source="__tests__/fixtures/action/all_fields_action.yml" -->