diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e981b06..0302e902 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,7 +80,7 @@ Please provide tests for your contribution. To generate a new fixture for Markdown output run ```bash -./lib/cli.js --no-banner -a __tests__/fixtures/.yml | \ +./lib/cli.js --no-banner -s __tests__/fixtures/.yml | \ tail -r | tail -n +2 | tail -r > .output ``` @@ -88,7 +88,7 @@ For creating a README.md fixture, first create the readme input file for the tes ```bash -./lib/cli.js --no-banner -a __tests__/fixtures/.yml -u __tests_/fixtures/.output +./lib/cli.js --no-banner -s __tests__/fixtures/.yml -u __tests_/fixtures/.output ``` ### Use a Consistent Coding Style diff --git a/README.md b/README.md index 49900887..ab5cf237 100644 --- a/README.md +++ b/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 - + - # applicable for actions only + # applicable for actions only - + - + - # applicable for actions only + # applicable for actions only ``` Optionally you can also add the following section to generate a usage guide, replacing \ and \ with the name and version of your project you would like to appear in your usage guide. ```md - + ``` ### Generate docs via CLI @@ -57,15 +57,18 @@ 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 @@ -73,23 +76,23 @@ 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`. ```md - + - + - + - + - + ``` For updating other Markdown files add the name of the file to the command `action-docs -u `. 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 diff --git a/__tests__/cli.test.ts b/__tests__/cli.test.ts index 4a91a47f..679fa083 100644 --- a/__tests__/cli.test.ts +++ b/__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 = ( @@ -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 = ( @@ -88,7 +88,7 @@ async function testReadme( const original = readFileSync(originalReadme, "utf-8"); const result = await cli( - `-u ${originalReadme} -a ${actionFile} ${extraArgs}`, + `-u ${originalReadme} -s ${actionFile} ${extraArgs}`, ); expect(result.code).toBe(exitCode); diff --git a/__tests__/fixtures/action/action_docs_action_readme.input b/__tests__/fixtures/action/action_docs_action_readme.input index b5c49f07..4340117c 100644 --- a/__tests__/fixtures/action/action_docs_action_readme.input +++ b/__tests__/fixtures/action/action_docs_action_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/action/action_docs_action_readme.output b/__tests__/fixtures/action/action_docs_action_readme.output index d924d3b7..2859f741 100644 --- a/__tests__/fixtures/action/action_docs_action_readme.output +++ b/__tests__/fixtures/action/action_docs_action_readme.output @@ -1,4 +1,4 @@ - + ## Inputs | name | description | required | default | @@ -7,4 +7,4 @@ | `actionFile` |

The action definition file.

| `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `false` | `LF` | - + diff --git a/__tests__/fixtures/action/action_usage_readme.input b/__tests__/fixtures/action/action_usage_readme.input index 1ece7460..a2ea167e 100644 --- a/__tests__/fixtures/action/action_usage_readme.input +++ b/__tests__/fixtures/action/action_usage_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/action/action_usage_readme.output b/__tests__/fixtures/action/action_usage_readme.output index c3599e14..acceeb00 100644 --- a/__tests__/fixtures/action/action_usage_readme.output +++ b/__tests__/fixtures/action/action_usage_readme.output @@ -1,4 +1,4 @@ - + ## Usage ```yaml @@ -22,4 +22,4 @@ # Required: false # Default: test ``` - + diff --git a/__tests__/fixtures/action/all_fields_readme.input b/__tests__/fixtures/action/all_fields_readme.input index e8d2547d..a7331adf 100644 --- a/__tests__/fixtures/action/all_fields_readme.input +++ b/__tests__/fixtures/action/all_fields_readme.input @@ -1,11 +1,11 @@ - + - + - + - + - + - + diff --git a/__tests__/fixtures/action/all_fields_readme.input.crlf b/__tests__/fixtures/action/all_fields_readme.input.crlf index f8ed910e..5c15f53f 100644 --- a/__tests__/fixtures/action/all_fields_readme.input.crlf +++ b/__tests__/fixtures/action/all_fields_readme.input.crlf @@ -1,7 +1,7 @@ - + - + - + - + diff --git a/__tests__/fixtures/action/all_fields_readme.output b/__tests__/fixtures/action/all_fields_readme.output index 6a1de0e6..1af27309 100644 --- a/__tests__/fixtures/action/all_fields_readme.output +++ b/__tests__/fixtures/action/all_fields_readme.output @@ -1,14 +1,14 @@ - + ## An Action - + - + ### Description Default test - + - + ### Usage ```yaml @@ -44,9 +44,9 @@ Default test # Required: false # Default: false ``` - + - + ### Inputs | name | description | required | default | @@ -56,19 +56,19 @@ Default test | `inputC` |

A description C

| `true` | `C` | | `inputD` |

A description D

| `false` | `D` | | `inputE` |

A description E

| `false` | `false` | - + - + ### Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + - + ### Runs This action is a `node12` action. - + diff --git a/__tests__/fixtures/action/all_fields_readme.output.crlf b/__tests__/fixtures/action/all_fields_readme.output.crlf index e92a4cc0..c7024423 100644 --- a/__tests__/fixtures/action/all_fields_readme.output.crlf +++ b/__tests__/fixtures/action/all_fields_readme.output.crlf @@ -1,10 +1,10 @@ - + ## Description Default test - + - + ## Inputs | name | description | required | default | @@ -14,19 +14,19 @@ Default test | `inputC` |

A description C

| `true` | `C` | | `inputD` |

A description D

| `false` | `D` | | `inputE` |

A description E

| `false` | `false` | - + - + ## Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + - + ## Runs This action is a `node12` action. - + diff --git a/__tests__/fixtures/action/all_fields_readme_filled.input b/__tests__/fixtures/action/all_fields_readme_filled.input index ba6a5ae6..b4ea42b2 100644 --- a/__tests__/fixtures/action/all_fields_readme_filled.input +++ b/__tests__/fixtures/action/all_fields_readme_filled.input @@ -1,12 +1,12 @@ - + ## Description Default test - + - + ## Inputs | name | description | required | default | @@ -19,9 +19,9 @@ Default test - + - + ## Outputs | name | description | @@ -31,12 +31,12 @@ Default test - + - + ## Run This action is a `docker` action. - + diff --git a/__tests__/fixtures/action/all_fields_readme_filled.output b/__tests__/fixtures/action/all_fields_readme_filled.output index 66747afc..48a6d08d 100644 --- a/__tests__/fixtures/action/all_fields_readme_filled.output +++ b/__tests__/fixtures/action/all_fields_readme_filled.output @@ -1,10 +1,10 @@ - + ## Description Default test - + - + ## Inputs | name | description | required | default | @@ -14,19 +14,19 @@ Default test | `inputC` |

A description C

| `true` | `C` | | `inputD` |

A description D

| `false` | `D` | | `inputE` |

A description E

| `false` | `false` | - + - + ## Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + - + ## Runs This action is a `node12` action. - + diff --git a/__tests__/fixtures/action/all_fields_readme_header.output b/__tests__/fixtures/action/all_fields_readme_header.output index b434acfe..9d1d70c4 100644 --- a/__tests__/fixtures/action/all_fields_readme_header.output +++ b/__tests__/fixtures/action/all_fields_readme_header.output @@ -1,14 +1,14 @@ - + # Test Action - + - + ## Description Default test - + - + ## Usage ```yaml @@ -46,9 +46,9 @@ Default test ``` - + - + ## Inputs | name | description | required | default | @@ -58,19 +58,19 @@ Default test | `inputC` |

A description C

| `true` | `C` | | `inputD` |

A description D

| `false` | `D` | | `inputE` |

A description E

| `false` | `false` | - + - + ## Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + - + ## Runs This action is a `node12` action. - + diff --git a/__tests__/fixtures/action/all_fields_usage_readme.input b/__tests__/fixtures/action/all_fields_usage_readme.input index edfa45de..1226a938 100644 --- a/__tests__/fixtures/action/all_fields_usage_readme.input +++ b/__tests__/fixtures/action/all_fields_usage_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/action/all_fields_usage_readme.output b/__tests__/fixtures/action/all_fields_usage_readme.output index ab9c69a2..0bd7c8cc 100644 --- a/__tests__/fixtures/action/all_fields_usage_readme.output +++ b/__tests__/fixtures/action/all_fields_usage_readme.output @@ -1,4 +1,4 @@ - + ## Usage ```yaml @@ -34,4 +34,4 @@ # Required: false # Default: false ``` - + diff --git a/__tests__/fixtures/action/two_actions_readme.input b/__tests__/fixtures/action/two_actions_readme.input index 72f32166..44c1d5c1 100644 --- a/__tests__/fixtures/action/two_actions_readme.input +++ b/__tests__/fixtures/action/two_actions_readme.input @@ -1,4 +1,4 @@ - + ## Inputs | name | description | required | default | @@ -7,6 +7,6 @@ | `actionFile` |

The action definition file.

| `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `false` | `LF` | - + - + diff --git a/__tests__/fixtures/action/two_actions_readme.output b/__tests__/fixtures/action/two_actions_readme.output index 0a4ecb6e..66b1c8ca 100644 --- a/__tests__/fixtures/action/two_actions_readme.output +++ b/__tests__/fixtures/action/two_actions_readme.output @@ -1,4 +1,4 @@ - + ## Inputs | name | description | required | default | @@ -7,13 +7,13 @@ | `actionFile` |

The action definition file.

| `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `false` | `LF` | - + - + ## Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + diff --git a/__tests__/fixtures/workflow/action_docs_workflow_readme.input b/__tests__/fixtures/workflow/action_docs_workflow_readme.input index 62017e53..e4308b60 100644 --- a/__tests__/fixtures/workflow/action_docs_workflow_readme.input +++ b/__tests__/fixtures/workflow/action_docs_workflow_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/workflow/action_docs_workflow_readme.output b/__tests__/fixtures/workflow/action_docs_workflow_readme.output index 8fad89cb..e4f6835b 100644 --- a/__tests__/fixtures/workflow/action_docs_workflow_readme.output +++ b/__tests__/fixtures/workflow/action_docs_workflow_readme.output @@ -1,4 +1,4 @@ - + ### Inputs | name | description | type | required | default | @@ -7,4 +7,4 @@ | `actionFile` |

The action definition file.

| `string` | `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `string` | `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `string` | `false` | `LF` | - + diff --git a/__tests__/fixtures/workflow/all_fields_readme.input b/__tests__/fixtures/workflow/all_fields_readme.input index 8b604b15..e1c89117 100644 --- a/__tests__/fixtures/workflow/all_fields_readme.input +++ b/__tests__/fixtures/workflow/all_fields_readme.input @@ -1,7 +1,7 @@ - + - + - + - + diff --git a/__tests__/fixtures/workflow/all_fields_readme.input.crlf b/__tests__/fixtures/workflow/all_fields_readme.input.crlf index 53cf3f12..c0413e77 100644 --- a/__tests__/fixtures/workflow/all_fields_readme.input.crlf +++ b/__tests__/fixtures/workflow/all_fields_readme.input.crlf @@ -1,5 +1,5 @@ - + - + - + diff --git a/__tests__/fixtures/workflow/all_fields_readme.output b/__tests__/fixtures/workflow/all_fields_readme.output index 938d16c9..b1d23544 100644 --- a/__tests__/fixtures/workflow/all_fields_readme.output +++ b/__tests__/fixtures/workflow/all_fields_readme.output @@ -1,8 +1,8 @@ - + ## A Workflow - + - + ### Usage ```yaml @@ -45,9 +45,9 @@ jobs: # Required: false # Default: false ``` - + - + ### Inputs | name | description | type | required | default | @@ -57,13 +57,13 @@ jobs: | `inputC` |

A description C

| `string` | `true` | `C` | | `inputD` |

A description D

| `string` | `false` | `D` | | `inputE` |

A description E

| `string` | `false` | `false` | - + - + ### Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + diff --git a/__tests__/fixtures/workflow/all_fields_readme.output.crlf b/__tests__/fixtures/workflow/all_fields_readme.output.crlf index a4ef46c5..12433a66 100644 --- a/__tests__/fixtures/workflow/all_fields_readme.output.crlf +++ b/__tests__/fixtures/workflow/all_fields_readme.output.crlf @@ -1,8 +1,8 @@ - + ## A Workflow - + - + ### Inputs | name | description | type | required | default | @@ -12,13 +12,13 @@ | `inputC` |

A description C

| `string` | `true` | `C` | | `inputD` |

A description D

| `string` | `false` | `D` | | `inputE` |

A description E

| `string` | `false` | `false` | - + - + ### Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + diff --git a/__tests__/fixtures/workflow/all_fields_readme_filled.input b/__tests__/fixtures/workflow/all_fields_readme_filled.input index 71867880..83facff0 100644 --- a/__tests__/fixtures/workflow/all_fields_readme_filled.input +++ b/__tests__/fixtures/workflow/all_fields_readme_filled.input @@ -1,21 +1,21 @@ - + ## Description Anything here - + - + ## Inputs Anything here - + - + ## Outputs Anything here - + diff --git a/__tests__/fixtures/workflow/all_fields_readme_filled.output b/__tests__/fixtures/workflow/all_fields_readme_filled.output index 1f4e2c41..9a26cce4 100644 --- a/__tests__/fixtures/workflow/all_fields_readme_filled.output +++ b/__tests__/fixtures/workflow/all_fields_readme_filled.output @@ -1,8 +1,8 @@ - + ## A Workflow - + - + ### Inputs | name | description | type | required | default | @@ -12,13 +12,13 @@ | `inputC` |

A description C

| `string` | `true` | `C` | | `inputD` |

A description D

| `string` | `false` | `D` | | `inputE` |

A description E

| `string` | `false` | `false` | - + - + ### Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + diff --git a/__tests__/fixtures/workflow/all_fields_usage_readme.input b/__tests__/fixtures/workflow/all_fields_usage_readme.input index 8147a87e..9287ae2d 100644 --- a/__tests__/fixtures/workflow/all_fields_usage_readme.input +++ b/__tests__/fixtures/workflow/all_fields_usage_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/workflow/all_fields_usage_readme.output b/__tests__/fixtures/workflow/all_fields_usage_readme.output index 0675cc1b..36345839 100644 --- a/__tests__/fixtures/workflow/all_fields_usage_readme.output +++ b/__tests__/fixtures/workflow/all_fields_usage_readme.output @@ -1,4 +1,4 @@ - + ### Usage ```yaml @@ -41,4 +41,4 @@ jobs: # Required: false # Default: false ``` - + diff --git a/__tests__/fixtures/workflow/two_workflows_readme.input b/__tests__/fixtures/workflow/two_workflows_readme.input index 2b614aef..44c572b9 100644 --- a/__tests__/fixtures/workflow/two_workflows_readme.input +++ b/__tests__/fixtures/workflow/two_workflows_readme.input @@ -1,4 +1,4 @@ - + ### Inputs | name | description | required | default | @@ -7,6 +7,6 @@ | `actionFile` |

The action definition file.

| `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `false` | `LF` | - + - + diff --git a/__tests__/fixtures/workflow/two_workflows_readme.output b/__tests__/fixtures/workflow/two_workflows_readme.output index ffdf257c..3cdeae22 100644 --- a/__tests__/fixtures/workflow/two_workflows_readme.output +++ b/__tests__/fixtures/workflow/two_workflows_readme.output @@ -1,4 +1,4 @@ - + ### Inputs | name | description | required | default | @@ -7,13 +7,13 @@ | `actionFile` |

The action definition file.

| `false` | `action.yml` | | `tocLevel` |

TOC level used for the headers.

| `false` | `2` | | `lineBreaks` |

Line breaks to be used in updated readme (LF|CR|CRLF).

| `false` | `LF` | - + - + ### Outputs | name | description | | --- | --- | | `outputA` |

A description A

| | `outputB` |

A description B

| - + diff --git a/__tests__/fixtures/workflow/workflow_usage_readme.input b/__tests__/fixtures/workflow/workflow_usage_readme.input index 656798cf..1fb0ac07 100644 --- a/__tests__/fixtures/workflow/workflow_usage_readme.input +++ b/__tests__/fixtures/workflow/workflow_usage_readme.input @@ -1 +1 @@ - + diff --git a/__tests__/fixtures/workflow/workflow_usage_readme.output b/__tests__/fixtures/workflow/workflow_usage_readme.output index 632d2162..e2b46d6b 100644 --- a/__tests__/fixtures/workflow/workflow_usage_readme.output +++ b/__tests__/fixtures/workflow/workflow_usage_readme.output @@ -1,4 +1,4 @@ - + ### Usage ```yaml @@ -26,4 +26,4 @@ jobs: # Required: true # Default: "" ``` - + diff --git a/package.json b/package.json index 26c492e5..48c26289 100644 --- a/package.json +++ b/package.json @@ -19,8 +19,9 @@ "test-cli": "nyc jest --testTimeout=10000 --silent --testMatch=**/cli*test.ts && nyc report --reporter=lcov --reporter=html --report-dir=./coverage_nyc", "test-action": "nyc jest --testTimeout=10000 --silent --testMatch=**/action-docs-action.test.ts --coverage=false", "test-workflow": "nyc jest --testTimeout=10000 --silent --testMatch=**/action-docs-workflow.test.ts --coverage=false", - "dev-action": "yarn run build && node lib/cli.js -a __tests__/fixtures/action/action.yml", - "dev-workflow": "yarn run build && node lib/cli.js -a __tests__/fixtures/workflow/workflow.yml", + "dev-action": "yarn run build && node lib/cli.js -s __tests__/fixtures/action/action.yml", + "dev-workflow": "yarn run build && node lib/cli.js -s __tests__/fixtures/workflow/workflow.yml", + "help": "yarn run build && node lib/cli.js --help", "all": "yarn run build && yarn run format && yarn run lint && yarn test" }, "repository": { diff --git a/src/action-docs.ts b/src/action-docs.ts index 9e875064..16e30693 100644 --- a/src/action-docs.ts +++ b/src/action-docs.ts @@ -313,12 +313,12 @@ async function updateReadme( const readmeFileText = String(readFileSync(options.readmeFile, "utf-8")); const match = readmeFileText.match( new RegExp( - `.?`, + `.?`, ), ) as string[]; if (match) { - const commentExpression = ``; + const commentExpression = ``; const regexp = new RegExp( `${escapeRegExp(commentExpression)}(?:(?:\r\n|\r|\n.*)+${escapeRegExp(commentExpression)})?`, ); @@ -340,7 +340,7 @@ async function updateReadme( }); } } else { - const commentExpression = ``; + const commentExpression = ``; const regexp = new RegExp( `${escapeRegExp(commentExpression)}(?:(?:\r\n|\r|\n.*)+${escapeRegExp(commentExpression)})?`, ); diff --git a/src/cli.ts b/src/cli.ts index 67259740..89872f8f 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -21,6 +21,14 @@ const args = await yargs(process.argv.slice(2)) default: defaultOptions.actionFile, demandOption: false, alias: "a", + deprecated: 'use "source" instead', + }, + source: { + description: "GitHub source file", + type: "string", + default: defaultOptions.actionFile, + demandOption: false, + alias: "s", }, "no-banner": { description: "Print no banner", @@ -56,7 +64,7 @@ args.banner === undefined && const updateReadme = args["update-readme"] !== undefined; const options = { - actionFile: args.action, + actionFile: args.source ?? args.action, tocLevel: args["toc-level"], updateReadme, readmeFile: