Skip to content

Commit

Permalink
chore(docs): add autogenerated flags reference
Browse files Browse the repository at this point in the history
  • Loading branch information
czeslavo committed Oct 2, 2023
1 parent be62bf7 commit f25e6e0
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 2 deletions.
14 changes: 12 additions & 2 deletions .github/workflows/release_docs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,24 @@ jobs:
path: docs.konghq.com
fetch-depth: 0

- name: Generate docs
- name: Generate CRDs reference
run: |
./scripts/apidocs-gen/post-process-for-konghq.sh \
docs.konghq.com/app/_src/kubernetes-ingress-controller/references/custom-resources-${{ steps.semver_parser.outputs.major }}.${{ steps.semver_parser.outputs.minor }}.x.md
- name: Generate flags reference
run: |
go run ./hack/generators/cli-arguments-markdown > docs.konghq.com/app/_src/kubernetes-ingress-controller/references/cli-arguments-${{ steps.semver_parser.outputs.major }}.${{ steps.semver_parser.outputs.minor }}.x.md
- name: Detect changes
id: detect-changes
run: echo "HAS_CHANGES=$(cd docs.konghq.com && git status --porcelain)" >> $GITHUB_OUTPUT
run: |
if [[ `cd docs.konghq.com && git status --porcelain` ]]; then
echo "Changes detected in docs repo"
echo "HAS_CHANGES=true" >> $GITHUB_OUTPUT
else
echo "No changes detected in docs repo"
fi
- name: GPG sign the commits
uses: crazy-max/ghaction-import-gpg@82a020f1f7f605c65dd2449b392a52c3fcfef7ef
Expand Down
52 changes: 52 additions & 0 deletions hack/generators/cli-arguments-markdown/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
package main

import (
"fmt"
"strings"

"github.com/kong/kubernetes-ingress-controller/v2/internal/manager"
"github.com/spf13/pflag"
)

// This program generates markdown documentation for the KIC executable's flags.
// It skips deprecated and hidden flags.
func main() {
cfg := manager.Config{}
flags := cfg.FlagSet()

markdown := strings.Builder{}
markdown.WriteString("---\ntitle: CLI Arguments\n---<!-- vale off -->\n\nVarious settings and configurations of the controller can be tweaked\nusing CLI flags.\n\n## Environment variables\n\nEach flag defined in the table below can also be configured using\nan environment variable. The name of the environment variable is `CONTROLLER_`\nstring followed by the name of flag in uppercase.\n\nFor example, `--ingress-class` can be configured using the following\nenvironment variable:\n\n```\nCONTROLLER_INGRESS_CLASS=kong-foobar\n```\n\nIt is recommended that all the configuration is done via environment variables\nand not CLI flags.\n\n")
markdown.WriteString("## Flags\n")
markdown.WriteString("| Flag | Type | Description | Default |\n")
markdown.WriteString("| ---- | ---- | ----------- | ------- |\n")

flags.VisitAll(func(flag *pflag.Flag) {
// Skip deprecated flags.
if flag.Deprecated != "" {
return
}

name := fmt.Sprintf("`--%s`", flag.Name)
typ := fmt.Sprintf("`%s`", flag.Value.Type())

description := flag.Usage
// Make sure the first letter is capitalized.
if first := description[0]; first >= 'a' && first <= 'z' {
description = strings.ToUpper(string(first)) + description[1:]
}
// Make sure the last character is a period.
if last := description[len(description)-1]; last != '.' {
description += "."
}

defaultValue := ""
if flag.DefValue != "" {
defaultValue = fmt.Sprintf("`%s`", flag.DefValue)
}

markdown.WriteString(fmt.Sprintf("| %s | %s | %s | %s |\n", name, typ, description, defaultValue))
})

markdown.WriteString("\n<!-- vale on -->\n")
fmt.Println(markdown.String())
}

0 comments on commit f25e6e0

Please sign in to comment.