feat: add support for code documentation

.github/workflows/test.yml

@@ -132,6 +132,7 @@ jobs:
 
       - name: Test action
         uses: ./
+        if: github.event_name == 'push'
 
       - name: Run build
         run: make build

README.md

@@ -64,21 +64,25 @@ and/or `Description` (only supported by actions)
 
 <!-- AUTO-DOC-INPUT:START - Do not remove or modify this section -->
 
-|          INPUT          |  TYPE  | REQUIRED |    DEFAULT     |                                           DESCRIPTION                                            |
-|-------------------------|--------|----------|----------------|--------------------------------------------------------------------------------------------------|
-|        bin\_path         | string |  false   |                |                                   Path to the auto-doc binary                                    |
-|      col\_max\_width      | string |  false   |    `"1000"`    |                                      Max width of a column                                       |
-|      col\_max\_words      | string |  false   |     `"5"`      |                          Max number of words per line <br>in a column                            |
-|        filename         | string |  false   | `"action.yml"` |                                      Path to the yaml file                                       |
-|      input\_columns      | string |  false   |                |    List of action.yml **input** columns names <br>to display, default (display all columns)      |
-|     markdown\_links      | string |  false   |    `"true"`    |  Boolean indicating whether to output input, <br>output and secret names as markdown <br>links   |
-|         output          | string |  false   | `"README.md"`  |                                     Path to the output file                                      |
-|     output\_columns      | string |  false   |                |    List of action.yml **output** column names <br>to display, default (display all columns)      |
-|        reusable         | string |  false   |                |                 Boolean Indicating whether the file is <br>a reusable workflow                   |
-| reusable\_input\_columns  | string |  false   |                | List of reusable workflow **input** column <br>names to display, default (display all columns)   |
-| reusable\_output\_columns | string |  false   |                | List of reusable workflow **output** column <br>names to display, default (display all columns)  |
-| reusable\_secret\_columns | string |  false   |                | List of reusable workflow **secret** column <br>names to display, default (display all columns)  |
-|         version         | string |  false   |                |                                    The version number to run                                     |
+|          INPUT          |  TYPE  | REQUIRED |           DEFAULT            |                                           DESCRIPTION                                            |
+|-------------------------|--------|----------|------------------------------|--------------------------------------------------------------------------------------------------|
+|        bin\_path         | string |  false   |                              |                                   Path to the auto-doc binary                                    |
+|      col\_max\_width      | string |  false   |           `"1000"`           |                                      Max width of a column                                       |
+|      col\_max\_words      | string |  false   |            `"5"`             |                          Max number of words per line <br>in a column                            |
+|        filename         | string |  false   |        `"action.yml"`        |                                      Path to the yaml file                                       |
+|      input\_columns      | string |  false   |                              |    List of action.yml **input** columns names <br>to display, default (display all columns)      |
+|     markdown\_links      | string |  false   |           `"true"`           |  Boolean indicating whether to output input, <br>output and secret names as markdown <br>links   |
+|         output          | string |  false   |        `"README.md"`         |                                     Path to the output file                                      |
+|     output\_columns      | string |  false   |                              |    List of action.yml **output** column names <br>to display, default (display all columns)      |
+|       repository        | string |  false   | `"${{ github.repository }}"` |                Repository name with owner. For example, <br>tj-actions/auto-doc                  |
+|        reusable         | string |  false   |                              |                 Boolean Indicating whether the file is <br>a reusable workflow                   |
+| reusable\_input\_columns  | string |  false   |                              | List of reusable workflow **input** column <br>names to display, default (display all columns)   |
+| reusable\_output\_columns | string |  false   |                              | List of reusable workflow **output** column <br>names to display, default (display all columns)  |
+| reusable\_secret\_columns | string |  false   |                              | List of reusable workflow **secret** column <br>names to display, default (display all columns)  |
+|          token          | string |  false   |   `"${{ github.token }}"`    |     GitHub token or Personal Access Token <br>used to fetch the repository latest <br>tag.       |
+|     use\_code\_blocks     | string |  false   |          `"false"`           |                                 Enable code block documentation                                  |
+|    use\_major\_version    | string |  false   |          `"false"`           |                Use the major version of the <br>repository tag e.g v1.0.0 -> v1                  |
+|         version         | string |  false   |                              |                                    The version number to run                                     |
 
 <!-- AUTO-DOC-INPUT:END -->
 
@@ -156,18 +160,22 @@ Automatically generate documentation for your custom github action or reusable w
 
 ### Flags
 
-    --colMaxWidth string                  Max width of a column (default "1000")
-    --colMaxWords string                  Max number of words per line in a column (default "6")
-    -f, --filename string                 config file
+        --colMaxWidth string                  Max width of a column. (default "1000")
+        --colMaxWords string                  Max number of words per line in a column. (default "6")
+    -f, --filename string                 config file.
     -h, --help                            help for auto-doc
-    --inputColumns stringArray            list of input column names (default [Input,Type,Required,Default,Description])
-    -m, --markdownLinks                   Names of inputs, outputs and secrets as markdown links
-    -o, --output string                   Output file (default "README.md")
-    --outputColumns stringArray           list of output column names (default [Output,Type,Description])
-    -r, --reusable                        A reusable workflow
-    --reusableInputColumns stringArray    list of reusable input column names (default [Input,Type,Required,Default,Description])
-    --reusableOutputColumns stringArray   list of reusable output column names (default [Output,Value,Description])
-    --reusableSecretColumns stringArray   list of reusable secrets column names (default [Secret,Required,Description])
+        --inputColumns stringArray            list of input column names. (default [Input,Type,Required,Default,Description])
+    -m, --markdownLinks                   Names of inputs, outputs and secrets as markdown links.
+    -o, --output string                   Output file. (default "README.md")
+        --outputColumns stringArray           list of output column names. (default [Output,Type,Description])
+        --repository string                   Repository name with owner. Example: tj-actions/auto-doc
+    -r, --reusable                        A reusable workflow.
+        --reusableInputColumns stringArray    list of reusable input column names. (default [Input,Type,Required,Default,Description])
+        --reusableOutputColumns stringArray   list of reusable output column names. (default [Output,Value,Description])
+        --reusableSecretColumns stringArray   list of reusable secrets column names. (default [Secret,Required,Description])
+        --token string                        GitHub token or Personal Access Token used to fetch the repository latest tag.
+        --useCodeBlocks                       Enable code block documentation.
+        --useMajorVersion                     Use the major version of the repository tag. Example: v1.0.0 -> v                 Use the major version of the repository tag. e.g v1.0.0 -> v1
 
 *   Free software: [Apache License 2.0](LICENSE)
 

action.yml

@@ -46,6 +46,23 @@ inputs:
     description: 'Boolean indicating whether to output input, output and secret names as markdown links'
     required: false
     default: 'true'
+  repository:
+    description: 'Repository name with owner. For example, tj-actions/auto-doc'
+    required: false
+    default: ${{ github.repository }}
+  token:
+    description: 'GitHub token or Personal Access Token used to fetch the repository latest tag.'
+    required: false
+    default: ${{ github.token }}
+  use_code_blocks:
+    description: 'Enable code block documentation'
+    required: false
+    default: 'false'
+  use_major_version:
+    description: 'Use the major version of the repository tag e.g v1.0.0 -> v1'
+    required: false
+    default: 'false'
+
 
 runs:
   using: 'composite'
@@ -79,6 +96,10 @@ runs:
         INPUT_REUSABLE: ${{ inputs.reusable }}
         INPUT_VERSION: ${{ inputs.version }}
         INPUT_MARKDOWN_LINKS: ${{ inputs.markdown_links }}
+        INPUT_REPOSITORY: ${{ inputs.repository }}
+        INPUT_TOKEN: ${{ inputs.token }}
+        INPUT_USE_CODE_BLOCKS: ${{ inputs.use_code_blocks }}
+        INPUT_USE_MAJOR_VERSION: ${{ inputs.use_major_version }}
 
 branding:
   icon: file-text

cmd/root.go

@@ -29,6 +29,8 @@ var fileName string
 var outputFileName string
 var colMaxWidth string
 var colMaxWords string
+var repository string
+var token string
 
 // action.yml
 var inputColumns []string
@@ -70,6 +72,22 @@ func RootCmdRunE(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	useCodeBlocks, err := cmd.Flags().GetBool("useCodeBlocks")
+	// coverage:ignore
+	if err != nil {
+		return err
+	}
+
+	useMajorVersion, err := cmd.Flags().GetBool("useMajorVersion")
+	// coverage:ignore
+	if err != nil {
+		return err
+	}
+
+	if repository == "" && useCodeBlocks {
+		return fmt.Errorf("repository must be specified with --repository")
+	}
+
 	var documentation types.Documentation
 
 	if reusable {
@@ -83,6 +101,18 @@ func RootCmdRunE(cmd *cobra.Command, args []string) error {
 			SecretColumns:      reusableSecretColumns,
 			InputMarkdownLinks: markdownLinks,
 		}
+	} else if useCodeBlocks {
+		documentation = &types.CodeBlock{
+			Repository:         repository,
+			Token:              token,
+			UseMajorVersion:    useMajorVersion,
+			InputFileName:      fileName,
+			OutputFileName:     outputFileName,
+			OutputColumns:      outputColumns,
+			ColMaxWidth:        colMaxWidth,
+			ColMaxWords:        colMaxWords,
+			InputMarkdownLinks: markdownLinks,
+		}
 	} else {
 		documentation = &types.Action{
 			InputFileName:      fileName,
@@ -129,68 +159,90 @@ func RootCmdFlags(cmd *cobra.Command) {
 		"filename",
 		"f",
 		"",
-		"config file",
+		"config file.",
 	)
 	cmd.Flags().BoolP(
 		"reusable",
 		"r",
 		false,
-		"A reusable workflow",
+		"A reusable workflow.",
 	)
 	cmd.Flags().StringVarP(
 		&outputFileName,
 		"output",
 		"o",
 		"README.md",
-		"Output file",
+		"Output file.",
 	)
 	cmd.Flags().StringVar(
 		&colMaxWidth,
 		"colMaxWidth",
 		"1000",
-		"Max width of a column",
+		"Max width of a column.",
 	)
 	cmd.Flags().StringVar(
 		&colMaxWords,
 		"colMaxWords",
 		"6",
-		"Max number of words per line in a column",
+		"Max number of words per line in a column.",
 	)
 	cmd.Flags().StringArrayVar(
 		&inputColumns,
 		"inputColumns",
 		internal.DefaultActionInputColumns,
-		"list of input column names",
+		"list of input column names.",
 	)
 	cmd.Flags().StringArrayVar(
 		&outputColumns,
 		"outputColumns",
 		internal.DefaultActionOutputColumns,
-		"list of output column names",
+		"list of output column names.",
 	)
 	cmd.Flags().StringArrayVar(
 		&reusableInputColumns,
 		"reusableInputColumns",
 		internal.DefaultReusableInputColumns,
-		"list of reusable input column names",
+		"list of reusable input column names.",
 	)
 	cmd.Flags().StringArrayVar(
 		&reusableOutputColumns,
 		"reusableOutputColumns",
 		internal.DefaultReusableOutputColumns,
-		"list of reusable output column names",
+		"list of reusable output column names.",
 	)
 	cmd.Flags().StringArrayVar(
 		&reusableSecretColumns,
 		"reusableSecretColumns",
 		internal.DefaultReusableSecretColumns,
-		"list of reusable secrets column names",
+		"list of reusable secrets column names.",
 	)
 	cmd.Flags().BoolP(
 		"markdownLinks",
 		"m",
 		false,
-		"Names of inputs, outputs and secrets as markdown links",
+		"Names of inputs, outputs and secrets as markdown links.",
+	)
+	cmd.Flags().StringVar(
+		&repository,
+		"repository",
+		"",
+		"Repository name with owner. Example: tj-actions/auto-doc",
+	)
+	cmd.Flags().StringVar(
+		&token,
+		"token",
+		"",
+		"GitHub token or Personal Access Token used to fetch the repository latest tag.",
+	)
+	cmd.Flags().Bool(
+		"useCodeBlocks",
+		false,
+		"Enable code block documentation.",
+	)
+	cmd.Flags().Bool(
+		"useMajorVersion",
+		false,
+		"Use the major version of the repository tag. Example: v1.0.0 -> v1",
 	)
 }
 

cmd/root_test.go

@@ -259,7 +259,7 @@ func Test_rootCommand(t *testing.T) {
 		}
 	})
 
-	t.Run("Update test/README-reusable.md using custom action file and output file", func(t *testing.T) {
+	t.Run("Update test/README-reusable.md using custom reusable workflow file and output file", func(t *testing.T) {
 		cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
 		RootCmdFlags(cmd)
 		b := bytes.NewBufferString("")
@@ -515,4 +515,62 @@ func Test_rootCommand(t *testing.T) {
 			)
 		}
 	})
+
+	t.Run("Update test/README-codeBlocks.md using custom action file and output file", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
+		RootCmdFlags(cmd)
+		b := bytes.NewBufferString("")
+		cmd.SetOut(b)
+		inputFile := filepath.Join("..", "test", "action.yml")
+		mdFile := filepath.Join("..", "test", "README-codeBlocks.md")
+		cmd.SetArgs([]string{"--filename", inputFile, "--output", mdFile, "--repository", "tj-actions/changed-files", "--useCodeBlocks"})
+		err := cmd.Execute()
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		out, err := io.ReadAll(b)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		exp := fmt.Sprintln("Successfully generated documentation")
+
+		if string(out) != exp {
+			t.Fatalf(
+				"expected \"%s\" got \"%s\"",
+				exp,
+				string(out),
+			)
+		}
+	})
+
+	t.Run("Update test/README-codeBlocksMajorVersion.md using custom action file and output file", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
+		RootCmdFlags(cmd)
+		b := bytes.NewBufferString("")
+		cmd.SetOut(b)
+		inputFile := filepath.Join("..", "test", "action.yml")
+		mdFile := filepath.Join("..", "test", "README-codeBlocksMajorVersion.md")
+		cmd.SetArgs([]string{"--filename", inputFile, "--output", mdFile, "--repository", "tj-actions/changed-files", "--useCodeBlocks", "--useMajorVersion"})
+		err := cmd.Execute()
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		out, err := io.ReadAll(b)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		exp := fmt.Sprintln("Successfully generated documentation")
+
+		if string(out) != exp {
+			t.Fatalf(
+				"expected \"%s\" got \"%s\"",
+				exp,
+				string(out),
+			)
+		}
+	})
 }

entrypoint.sh

@@ -68,6 +68,26 @@ if [[ "$INPUT_MARKDOWN_LINKS" == "true" ]]; then
   EXTRA_ARGS="${EXTRA_ARGS} --markdownLinks"
 fi
 
+# repository
+if [[ -n "$INPUT_REPOSITORY" ]]; then
+  EXTRA_ARGS="${EXTRA_ARGS} --repository=${INPUT_REPOSITORY}"
+fi
+
+# token
+if [[ -n "$INPUT_TOKEN" ]]; then
+  EXTRA_ARGS="${EXTRA_ARGS} --token=${INPUT_TOKEN}"
+fi
+
+# use_code_blocks
+if [[ "$INPUT_USE_CODE_BLOCKS" == "true" ]]; then
+  EXTRA_ARGS="${EXTRA_ARGS} --useCodeBlocks"
+fi
+
+# use_major_version
+if [[ "$INPUT_USE_MAJOR_VERSION" == "true" ]]; then
+  EXTRA_ARGS="${EXTRA_ARGS} --useMajorVersion"
+fi
+
 echo "::debug::Generating documentation using ${BIN_PATH}..."
 echo "::debug::Extra args: ${EXTRA_ARGS}"
 

go.mod

@@ -10,8 +10,10 @@ require (
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/kr/pretty v0.2.0 // indirect
-	github.com/mattn/go-runewidth v0.0.9 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/mattn/go-runewidth v0.0.15 // indirect
+	github.com/rivo/uniseg v0.4.4 // indirect
+	github.com/rogpeppe/go-internal v1.11.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
-	gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 )