feat: support document generation for workflows

.eslintrc.json

@@ -55,7 +55,9 @@
     "@typescript-eslint/require-array-sort-compare": "error",
     "@typescript-eslint/restrict-plus-operands": "error",
     "@typescript-eslint/type-annotation-spacing": "error",
-    "@typescript-eslint/unbound-method": "error"
+    "@typescript-eslint/unbound-method": "error",
+      "no-shadow": "off",
+      "@typescript-eslint/no-shadow": "error"
   },
   "env": {
     "node": true,

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

@@ -6,26 +6,28 @@
 
 # Action docs
 
-A CLI to generate and update documentation for GitHub actions, based on the action definition `.yml`. To update your README in a GitHub workflow you can use the [action-docs-action](https://github.com/npalm/action-docs-action).
+A CLI to generate and update documentation for GitHub actions or workflows, based on the definition `.yml`. To update your README in a GitHub workflow you can use the [action-docs-action](https://github.com/npalm/action-docs-action).
 
 ## TL;DR
 
 ### Add the following comment blocks to your README.md
 
 ```md
-<!-- action-docs-description action="action.yml" -->
+<!-- action-docs-header source="action.yml" -->
 
-<!-- action-docs-inputs action="action.yml" -->
+<!-- action-docs-description source="action.yml" --> # applicable for actions only
 
-<!-- action-docs-outputs action="action.yml" -->
+<!-- action-docs-inputs source="action.yml" -->
 
-<!-- action-docs-runs action="action.yml" -->
+<!-- action-docs-outputs source="action.yml" -->
+
+<!-- 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
@@ -55,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
 
@@ -106,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__/action-docs.test.ts → __tests__/action-docs-action.test.ts

@@ -2,9 +2,9 @@ import { generateActionMarkdownDocs, Options } from "../src";
 import { readFileSync, writeFileSync, copyFileSync, unlink } from "fs";
 import * as path from "path";
 
-const fixtureDir = path.join("__tests__", "fixtures");
+const fixtureDir = path.join("__tests__", "fixtures", "action");
 
-// By default an 'action.yml' is expected at the runtime location. Therefore we copy one during th test.
+// By default an 'action.yml' is expected at the runtime location. Therefore we copy one during the test.
 beforeAll(() => {
   copyFileSync(path.join(fixtureDir, "action.yml"), "action.yml");
 });
@@ -61,11 +61,30 @@ describe("Test output", () => {
 
 describe("Test update readme ", () => {
   test("Empty readme (all fields)", async () => {
-    await testReadme({
-      actionFile: path.join(fixtureDir, "all_fields_action.yml"),
-      originalReadme: path.join(fixtureDir, "all_fields_readme.input"),
-      fixtureReadme: path.join(fixtureDir, "all_fields_readme.output"),
-    });
+    await testReadme(
+      {
+        actionFile: path.join(fixtureDir, "all_fields_action.yml"),
+        originalReadme: path.join(fixtureDir, "all_fields_readme.input"),
+        fixtureReadme: path.join(fixtureDir, "all_fields_readme.output"),
+      },
+      {
+        includeNameHeader: true,
+      },
+    );
+  });
+  test("Empty readme (all fields) with header", async () => {
+    await testReadme(
+      {
+        actionFile: path.join(fixtureDir, "all_fields_action.yml"),
+        originalReadme: path.join(fixtureDir, "all_fields_readme.input"),
+        fixtureReadme: path.join(fixtureDir, "all_fields_readme_header.output"),
+      },
+      {
+        includeNameHeader: true,
+      },
+      false,
+      true,
+    );
   });
 
   test("Filled readme (all fields)", async () => {
@@ -83,7 +102,9 @@ describe("Test update readme ", () => {
         originalReadme: path.join(fixtureDir, "all_fields_readme.input"),
         fixtureReadme: path.join(fixtureDir, "all_fields_readme_header.output"),
       },
-      {},
+      {
+        includeNameHeader: true,
+      },
       false,
       true,
     );
@@ -145,6 +166,21 @@ describe("Test usage format", () => {
   });
 });
 
+describe("Backwards compatibility", () => {
+  test("Deprecated action option still works correctly", async () => {
+    await testReadme(
+      {
+        actionFile: path.join(fixtureDir, "all_fields_action.yml"),
+        originalReadme: path.join(fixtureDir, "action_deprecated.input"),
+        fixtureReadme: path.join(fixtureDir, "action_deprecated.output"),
+      },
+      {
+        includeNameHeader: true,
+      },
+    );
+  });
+});
+
 interface ReadmeTestFixtures {
   actionFile: string;
   originalReadme: string;
@@ -160,18 +196,21 @@ async function testReadme(
   const expected = <string>readFileSync(files.fixtureReadme, "utf-8");
   const original = <string>readFileSync(files.originalReadme, "utf-8");
 
-  await generateActionMarkdownDocs({
-    actionFile: files.actionFile,
-    updateReadme: true,
-    includeNameHeader: includeNameHeader,
-    readmeFile: files.originalReadme,
-    ...overwriteOptions,
-  });
+  try {
+    await generateActionMarkdownDocs({
+      actionFile: files.actionFile,
+      updateReadme: true,
+      includeNameHeader: includeNameHeader,
+      readmeFile: files.originalReadme,
+      ...overwriteOptions,
+    });
 
-  const updated = <string>readFileSync(files.originalReadme, "utf-8");
+    const updated = <string>readFileSync(files.originalReadme, "utf-8");
 
-  if (doExpect) {
+    if (doExpect) {
+      expect(updated).toEqual(expected);
+    }
+  } finally {
     writeFileSync(files.originalReadme, original);
-    expect(updated).toEqual(expected);
   }
 }