Skip to content

Commit

Permalink
feat: add support for code documentation (#520)
Browse files Browse the repository at this point in the history 
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
  • Loading branch information
@jackton1 @github-actions
jackton1 and github-actions[bot] authored Nov 15, 2023
1 parent 37924e0 commit 65de8d3
Show file tree
Hide file tree
Showing 21 changed files with 982 additions and 182 deletions.
1 change: 1 addition & 0 deletions .github/workflows/test.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,7 @@ jobs:

- name: Test action
uses: ./
if: github.event_name == 'push'

- name: Run build
run: make build
Expand Down
60 changes: 34 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down Expand Up @@ -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)

Expand Down
21 changes: 21 additions & 0 deletions action.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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
Expand Down
74 changes: 63 additions & 11 deletions cmd/root.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 {
Expand All @@ -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,
Expand Down Expand Up @@ -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",
)
}

Expand Down
60 changes: 59 additions & 1 deletion cmd/root_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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("")
Expand Down Expand Up @@ -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),
)
}
})
}
20 changes: 20 additions & 0 deletions entrypoint.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}"

Expand Down
8 changes: 5 additions & 3 deletions go.mod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Loading

0 comments on commit 65de8d3

Please sign in to comment.