Skip to content

Commit

Permalink
feat: Add a new input to optionally set names as markdown anchors (#480)
Browse files Browse the repository at this point in the history 
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Tonye Jack <jtonye@ymail.com>
  • Loading branch information
@ViacheslavKudinov @github-actions @jackton1
3 people committed Jun 7, 2023
1 parent 5a8d1f8 commit b750d7a
Show file tree
Hide file tree
Showing 15 changed files with 432 additions and 46 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/test.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ on:
branches:
- main

permissions:
contents: write

jobs:
snapshot:
name: snapshot
Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ Add the `Inputs` and/or `Outputs` and/or `Secrets` (only supported by reusable w
| 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 | `"false"` | 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 |
Expand Down
5 changes: 5 additions & 0 deletions action.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ inputs:
version:
description: 'The version number to run'
required: false
markdown_links:
description: 'Boolean indicating whether to output input, output and secret names as markdown links'
required: false
default: 'false'

runs:
using: 'composite'
Expand Down Expand Up @@ -73,6 +77,7 @@ runs:
INPUT_REUSABLE_SECRET_COLUMNS: ${{ inputs.reusable_secret_columns }}
INPUT_REUSABLE: ${{ inputs.reusable }}
INPUT_VERSION: ${{ inputs.version }}
INPUT_MARKDOWN_LINKS: ${{ inputs.markdown_links }}
branding:
icon: file-text
Expand Down
38 changes: 25 additions & 13 deletions cmd/root.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,11 @@ func RootCmdRunE(cmd *cobra.Command, args []string) error {
}

reusable, err := cmd.Flags().GetBool("reusable")
if err != nil {
return err
}

markdownLinks, err := cmd.Flags().GetBool("markdownLinks")
if err != nil {
return err
}
Expand All @@ -68,22 +72,24 @@ func RootCmdRunE(cmd *cobra.Command, args []string) error {

if reusable {
documentation = &types.Reusable{
InputFileName: fileName,
OutputFileName: outputFileName,
ColMaxWidth: colMaxWidth,
ColMaxWords: colMaxWords,
InputColumns: reusableInputColumns,
OutputColumns: reusableOutputColumns,
SecretColumns: reusableSecretColumns,
InputFileName: fileName,
OutputFileName: outputFileName,
ColMaxWidth: colMaxWidth,
ColMaxWords: colMaxWords,
InputColumns: reusableInputColumns,
OutputColumns: reusableOutputColumns,
SecretColumns: reusableSecretColumns,
InputMarkdownLinks: markdownLinks,
}
} else {
documentation = &types.Action{
InputFileName: fileName,
OutputFileName: outputFileName,
ColMaxWidth: colMaxWidth,
ColMaxWords: colMaxWords,
InputColumns: inputColumns,
OutputColumns: outputColumns,
InputFileName: fileName,
OutputFileName: outputFileName,
ColMaxWidth: colMaxWidth,
ColMaxWords: colMaxWords,
InputColumns: inputColumns,
OutputColumns: outputColumns,
InputMarkdownLinks: markdownLinks,
}
}

Expand Down Expand Up @@ -176,6 +182,12 @@ func RootCmdFlags(cmd *cobra.Command) {
internal.DefaultReusableSecretColumns,
"list of reusable secrets column names",
)
cmd.Flags().BoolP(
"markdownLinks",
"m",
false,
"Names of inputs, outputs and secrets as markdown links",
)
}

func init() {
Expand Down
212 changes: 204 additions & 8 deletions cmd/root_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,154 @@ package cmd
import (
"bytes"
"fmt"
"io/ioutil"
"io"
"runtime"
"testing"

"github.com/spf13/cobra"
)

func Test_rootCommand(t *testing.T) {
t.Run("Missing filename flag", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
o := bytes.NewBufferString("")
b := bytes.NewBufferString("")
cmd.SetOut(o)
cmd.SetErr(b)
cmd.SetArgs([]string{"--filename", "", "--output", "../test/README.md"})
err := cmd.Execute()

if err == nil {
t.Fatal("expected error got nil")
}

out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}

exp := fmt.Sprintln("Error: filename must be specified with --filename")

if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
})

t.Run("Passing positional arguments", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
o := bytes.NewBufferString("")
b := bytes.NewBufferString("")
cmd.SetOut(o)
cmd.SetErr(b)
cmd.SetArgs([]string{"../test/action.yml"})
err := cmd.Execute()

if err == nil {
t.Fatal("expected error got nil")
}

out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}

exp := fmt.Sprintln("Error: requires no positional arguments: 1 given")

if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
})

t.Run("Non existent action file", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
o := bytes.NewBufferString("")
b := bytes.NewBufferString("")
cmd.SetOut(o)
cmd.SetErr(b)
cmd.SetArgs([]string{"--filename", "../test/invalid.yml", "--output", "../test/README.md"})
err := cmd.Execute()

if err == nil {
t.Fatal("expected error got nil")
}

out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}

if runtime.GOOS == "windows" {
exp := fmt.Sprintln("Error: open ../test/invalid.yml: The system cannot find the file specified.")
if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
} else {
exp := fmt.Sprintln("Error: open ../test/invalid.yml: no such file or directory")
if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
}
})

t.Run("Non existent reusable workflow file", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
o := bytes.NewBufferString("")
b := bytes.NewBufferString("")
cmd.SetOut(o)
cmd.SetErr(b)
cmd.SetArgs([]string{"--filename", "../test/reusable-invalid.yml", "--reusable", "--output", "../test/README-reusable.md"})
err := cmd.Execute()

if err == nil {
t.Fatal("expected error got nil")
}

out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}

if runtime.GOOS == "windows" {
exp := fmt.Sprintln("Error: open ../test/reusable-invalid.yml: The system cannot find the file specified.")
if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
} else {
exp := fmt.Sprintln("Error: open ../test/reusable-invalid.yml: no such file or directory")
if string(out) != exp {
t.Fatalf(
"expected \"%s\" got \"%s\"",
exp,
string(out),
)
}
}
})

t.Run("Update test/README.md using custom action file and output file", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
Expand All @@ -38,7 +179,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -66,7 +207,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -94,7 +235,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -122,7 +263,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -150,7 +291,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -178,7 +319,7 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -206,7 +347,62 @@ func Test_rootCommand(t *testing.T) {
t.Fatal(err)
}

out, err := ioutil.ReadAll(b)
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-markdownLinks.md using custom action file and output file and markdownLinks flag", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
b := bytes.NewBufferString("")
cmd.SetOut(b)
cmd.SetArgs([]string{"--filename", "../test/action.yml", "--output", "../test/README-markdownLinks.md", "--markdownLinks"})
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-reusable.md using custom action file and output file and markdownLinks flag", func(t *testing.T) {
cmd := &cobra.Command{Use: "auto-doc", RunE: RootCmdRunE}
RootCmdFlags(cmd)
b := bytes.NewBufferString("")
cmd.SetOut(b)
cmd.SetArgs([]string{"--filename", "../test/reusable-action.yml", "--reusable", "--output", "../test/README-reusable-markdownLinks.md", "-m"})
err := cmd.Execute()

if err != nil {
t.Fatal(err)
}

out, err := io.ReadAll(b)
if err != nil {
t.Fatal(err)
}
Expand Down
5 changes: 5 additions & 0 deletions entrypoint.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,11 @@ if [[ "$REUSABLE" == "true" ]]; then
EXTRA_ARGS="${EXTRA_ARGS} --reusable"
fi

# markdown links
if [[ "$INPUT_MARKDOWN_LINKS" == "true" ]]; then
EXTRA_ARGS="${EXTRA_ARGS} --markdownLinks"
fi

echo "::debug::Generating documentation using ${BIN_PATH}..."
echo "::debug::Extra args: ${EXTRA_ARGS}"

Expand Down

0 comments on commit b750d7a

Please sign in to comment.