Skip to content

Commit

Permalink
Merge pull request #409 from tj-actions/chore/fix-add-missing-comments
Browse files Browse the repository at this point in the history
chore: fix add missing comments
  • Loading branch information
repo-ranger[bot] committed Mar 9, 2023
2 parents fd86fa3 + 57a2454 commit 1cd7763
Show file tree
Hide file tree
Showing 11 changed files with 231 additions and 83 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/format-tidy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ jobs:
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add cmd main.go go.mod go.sum
git add cmd ${{ steps.verify-changed-files.outputs.changed_files }}
git commit -m "Formatted code."
- name: Push formatting changes
Expand Down
40 changes: 23 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
![Coverage](https://img.shields.io/badge/Coverage-82.4%25-brightgreen)
[![codecov](https://codecov.io/gh/tj-actions/auto-doc/branch/main/graph/badge.svg?token=TNXW4QRRJD)](https://codecov.io/gh/tj-actions/auto-doc)
![Coverage](https://img.shields.io/badge/Coverage-80.6%25-brightgreen)
[![codecov](https://codecov.io/github/tj-actions/auto-doc/branch/main/graph/badge.svg?token=TNXW4QRRJD)](https://codecov.io/github/tj-actions/auto-doc)
[![Go Reference](https://pkg.go.dev/badge/github.com/tj-actions/auto-doc.svg)](https://pkg.go.dev/github.com/tj-actions/auto-doc)
[![Go Report Card](https://goreportcard.com/badge/github.com/tj-actions/auto-doc)](https://goreportcard.com/report/github.com/tj-actions/auto-doc)
[![CI](https://github.com/tj-actions/auto-doc/workflows/CI/badge.svg)](https://github.com/tj-actions/auto-doc/actions?query=workflow%3ACI)
Expand All @@ -12,19 +12,21 @@
[![Windows](https://img.shields.io/badge/Windows-0078D6?logo=windows\&logoColor=white)](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)

<!-- ALL-CONTRIBUTORS-BADGE:END -->

## auto-doc

GitHub Action that generates beautiful, easy-to-read markdown tables with just a few lines of code. Say goodbye to manual table creation and hello to streamlined documentation that's always up-to-date.


## Features
- Document custom actions from the `action.yml` file
- Document reusable workflows by specifying the filename
- Easy to understand markdown table of all inputs/outputs/secrets.
- Fast and always up-to-date documentation

* Document custom actions from the `action.yml` file
* Document reusable workflows by specifying the filename
* Easy to understand markdown table of all inputs/outputs/secrets.
* Fast and always up-to-date documentation

## Table of Contents

Expand All @@ -34,9 +36,10 @@ GitHub Action that generates beautiful, easy-to-read markdown tables with just a
* [CLI](#cli)
* [Installation](#installation)
* [Synopsis](#synopsis)
* [Options](#options)
* [Flags](#flags)
* [Credits](#credits)
* [Report Bugs](#report-bugs)
* [Contributors ✨](#contributors-)

## Usage

Expand All @@ -56,17 +59,17 @@ Add the `Inputs` and/or `Outputs` and/or `Secrets` [`H2` header](https://github.

| 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 | `"6"` | Max number of words per line<br>in a column |
| 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 | `"6"` | 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) |
| input\_columns | string | false | | List of action.yml **input** columns names<br>to display, default (display all columns) |
| 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) |
| 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<br>columns) |
| reusable_output_columns | string | false | | List of reusable workflow **output** column<br> names to display, default (display all<br>columns) |
| reusable_secret_columns | string | false | | List of reusable workflow **secret** column<br> names to display, default (display all<br>columns) |
| reusable\_input\_columns | string | false | | List of reusable workflow **input** column<br> names to display, default (display all<br>columns) |
| reusable\_output\_columns | string | false | | List of reusable workflow **output** column<br> names to display, default (display all<br>columns) |
| reusable\_secret\_columns | string | false | | List of reusable workflow **secret** column<br> names to display, default (display all<br>columns) |

<!-- AUTO-DOC-INPUT:END -->

Expand Down Expand Up @@ -144,7 +147,6 @@ Auto generate documentation for your github action.
--reusableOutputColumns stringArray list of reusable output column names (default [Output,Value,Description])
--reusableSecretColumns stringArray list of reusable secrets column names (default [Secret,Required,Description])


* Free software: [Apache License 2.0](LICENSE)

If you feel generous and want to show some extra appreciation:
Expand Down Expand Up @@ -178,8 +180,11 @@ If you are reporting a bug, please include:
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

<!-- prettier-ignore-start -->

<!-- markdownlint-disable -->

<table>
<tbody>
<tr>
Expand All @@ -189,6 +194,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
</table>

<!-- markdownlint-restore -->

<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->
Expand Down
22 changes: 11 additions & 11 deletions cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -66,22 +66,22 @@ func RootCmdRunE(cmd *cobra.Command, args []string) error {

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

Expand Down
16 changes: 16 additions & 0 deletions cmd/root_test.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,19 @@
// Package cmd provides a cli script that parses the GitHub action.yml and reusable workflow files and outputs a Markdown table to a specified path.
/*
Copyright © 2021 Tonye Jack <jtonye@ymail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package cmd

import (
Expand Down
47 changes: 45 additions & 2 deletions internal/constants.go
Original file line number Diff line number Diff line change
@@ -1,34 +1,77 @@
// Package internal/constants contains all internal constants
/*
Copyright © 2021 Tonye Jack <jtonye@ymail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package internal

import "fmt"

// InputsHeader represents the markdown header of inputs
const InputsHeader = "## Inputs"

// OutputsHeader represents the markdown header of outputs
const OutputsHeader = "## Outputs"

// SecretsHeader represents the markdown header of secrets
const SecretsHeader = "## Secrets"

// AutoDocStart placeholder that represents the start of the input table
const AutoDocStart = "<!-- AUTO-DOC-%s:START - Do not remove or modify this section -->"

// AutoDocEnd placeholder that represents the end of the input table
const AutoDocEnd = "<!-- AUTO-DOC-%s:END -->"

// PipeSeparator represents the separator used for the distinguishing between columns
const PipeSeparator = "|"

// NewLineSeparator used for splitting lines
const NewLineSeparator = "\n"

// InputAutoDocStart is the start of the input
var InputAutoDocStart = fmt.Sprintf(AutoDocStart, "INPUT")

// InputAutoDocEnd is the end of the input
var InputAutoDocEnd = fmt.Sprintf(AutoDocEnd, "INPUT")

// OutputAutoDocStart is the start of the output
var OutputAutoDocStart = fmt.Sprintf(AutoDocStart, "OUTPUT")

// OutputAutoDocEnd is the end of the output
var OutputAutoDocEnd = fmt.Sprintf(AutoDocEnd, "OUTPUT")

// SecretsAutoDocStart is the start of the secrets
var SecretsAutoDocStart = fmt.Sprintf(AutoDocStart, "SECRETS")

// SecretsAutoDocEnd is the end of the secrets
var SecretsAutoDocEnd = fmt.Sprintf(AutoDocEnd, "SECRETS")

// action.yml

// DefaultActionInputColumns default values
var DefaultActionInputColumns = []string{"Input", "Type", "Required", "Default", "Description"}

// DefaultActionOutputColumns default values
var DefaultActionOutputColumns = []string{"Output", "Type", "Description"}


// Reusable workflows

// DefaultReusableSecretColumns default values
var DefaultReusableSecretColumns = []string{"Secret", "Required", "Description"}

// DefaultReusableOutputColumns default values
var DefaultReusableOutputColumns = []string{"Output", "Value", "Description"}

// DefaultReusableInputColumns default values
var DefaultReusableInputColumns = []string{"Input", "Type", "Required", "Default", "Description"}
var DefaultReusableInputColumns = []string{"Input", "Type", "Required", "Default", "Description"}
67 changes: 32 additions & 35 deletions internal/types/action.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,19 @@
//Package types contains all defined types
/*
Copyright © 2021 Tonye Jack <jtonye@ymail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package types

import (
Expand Down Expand Up @@ -29,16 +45,17 @@ type ActionOutput struct {

// Action represents the action.yml
type Action struct {
InputFileName string
InputFileName string
OutputFileName string
ColMaxWidth string
ColMaxWords string
InputColumns []string
OutputColumns []string
Inputs map[string]ActionInput `yaml:"inputs,omitempty"`
Outputs map[string]ActionOutput `yaml:"outputs,omitempty"`
ColMaxWidth string
ColMaxWords string
InputColumns []string
OutputColumns []string
Inputs map[string]ActionInput `yaml:"inputs,omitempty"`
Outputs map[string]ActionOutput `yaml:"outputs,omitempty"`
}

// GetData parses the source yaml file
func (a *Action) GetData() error {
actionYaml, err := os.ReadFile(a.InputFileName)
if err != nil {
Expand All @@ -49,6 +66,7 @@ func (a *Action) GetData() error {
return err
}

// WriteDocumentation write the table to the output file
func (a *Action) WriteDocumentation(inputTable, outputTable *strings.Builder) error {
input, err := os.ReadFile(a.OutputFileName)

Expand Down Expand Up @@ -95,6 +113,7 @@ func (a *Action) WriteDocumentation(inputTable, outputTable *strings.Builder) er
return nil
}

// RenderOutput renders the output and writes it to the given output
func (a *Action) RenderOutput() error {
var err error
maxWidth, err := strconv.Atoi(a.ColMaxWidth)
Expand Down Expand Up @@ -125,7 +144,8 @@ func (a *Action) RenderOutput() error {
return nil
}

func renderActionInputTableOutput(i map[string]ActionInput, inputColumns[]string, maxWidth int, maxWords int) (*strings.Builder, error) {
// renderActionOutputTableOutput renders the action input table
func renderActionInputTableOutput(i map[string]ActionInput, inputColumns []string, maxWidth int, maxWords int) (*strings.Builder, error) {
inputTableOutput := &strings.Builder{}

if len(i) > 0 {
Expand All @@ -149,30 +169,6 @@ func renderActionInputTableOutput(i map[string]ActionInput, inputColumns[]string
inputTable.SetColWidth(maxWidth)

for _, key := range keys {
var inputDefault string
if len(i[key].Default) > 0 {
inputDefault = i[key].Default
var defaultValue string
var parts = strings.Split(inputDefault, "\n")

if len(parts) > 1 && inputDefault != internal.NewLineSeparator {
for _, part := range parts {
if part != "" {
defaultValue += "`\"" + part + "\"`" + "<br>"
}
}
} else {
if strings.Contains(inputDefault, internal.PipeSeparator) {
inputDefault = strings.Replace(inputDefault, internal.PipeSeparator, "\"\\"+internal.PipeSeparator+"\"", -1)
} else {
inputDefault = fmt.Sprintf("%#v", i[key].Default)
}
defaultValue = "`" + inputDefault + "`"
}

inputDefault = defaultValue
}

var row []string

for _, col := range inputColumns {
Expand All @@ -184,7 +180,7 @@ func renderActionInputTableOutput(i map[string]ActionInput, inputColumns[]string
case "Required":
row = append(row, strconv.FormatBool(i[key].Required))
case "Default":
row = append(row, inputDefault)
row = append(row, utils.FormatValue(i[key].Default))
case "Description":
row = append(row, utils.WordWrap(i[key].Description, maxWords))
default:
Expand Down Expand Up @@ -218,7 +214,8 @@ func renderActionInputTableOutput(i map[string]ActionInput, inputColumns[]string
return inputTableOutput, nil
}

func renderActionOutputTableOutput(o map[string]ActionOutput, outputColumns[]string, maxWidth int, maxWords int) (*strings.Builder, error) {
// renderActionOutputTableOutput renders the action output table
func renderActionOutputTableOutput(o map[string]ActionOutput, outputColumns []string, maxWidth int, maxWords int) (*strings.Builder, error) {
outputTableOutput := &strings.Builder{}

if len(o) > 0 {
Expand Down Expand Up @@ -279,4 +276,4 @@ func renderActionOutputTableOutput(o map[string]ActionOutput, outputColumns[]str
}
}
return outputTableOutput, nil
}
}
18 changes: 17 additions & 1 deletion internal/types/documentation.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,23 @@
//Package types contains all defined types
/*
Copyright © 2021 Tonye Jack <jtonye@ymail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package types

// Documentation is the interface for Action and Reusable
type Documentation interface {
GetData() error
RenderOutput() error
}
}

0 comments on commit 1cd7763

Please sign in to comment.