Streamline the process of generating AsciiDoc documentation from inline comments within source code files. This tool converts inline documentation into AsciiDoc files, tailored for seamless integration with Antora.
Maybe like this? https://cli.github.com/manual/gh ... I want a documentation about all commands (that means all subdommands as well).
Todo
[x] Implement manpage command
[x] Generate manpage.adoc from pipeline
[x] build the app before building docker image
Maybe this should be the first step after linting
[x] generate manpage alongside other docs
[x] commit
[x] run sonar in parallel
[x] build image
Copilot conversation
Q
do you kmow how I can generate a documentation for my go cobra cli app automatically? it should list all commands with all params similar to the --help command
A
Yes, Cobra provides a built-in way to generate documentation for your CLI application. You can generate man pages, markdown, or a bash completion script. Here's how you can generate markdown documentation:
First, you need to import the doc package from Cobra:
import "github.com/spf13/cobra/doc"
Then, you can generate the documentation for your root command and all its subcommands:
This will generate a markdown file for each command in your CLI application, with a filename based on the command's name. The files will be placed in the directory specified as the second argument to GenMarkdownTree.
Each markdown file will contain a description of the command, its usage, and its flags, similar to the output of the --help command.
Q
can this doccumentation be generated in asciidoc?
A
Yes, Cobra also supports generating documentation in Asciidoc format. Here's how you can do it:
First, you need to import the doc package from Cobra:
import "github.com/spf13/cobra/doc"
Then, you can generate the documentation for your root command and all its subcommands:
This will generate an Asciidoc file for each command in your CLI application, with a filename based on the command's name. The files will be placed in the directory specified as the second argument to GenAsciidocTree.
Each Asciidoc file will contain a description of the command, its usage, and its flags, similar to the output of the --help command.
Q
can I generate these docs from github actions workflow?
A
Yes, you can generate Cobra CLI documentation as part of a GitHub Actions workflow. Here's a basic example of how you might set up such a workflow:
name: Generate CLI Documentation
on:
push:
branches:
- main
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Set up Go
uses: actions/setup-go@v2
with:
go-version: 1.16
- name: Generate documentation
run: |
go get github.com/spf13/cobra/cobra
go run main.go doc # assuming your application's entry point is main.go and "doc" is a command to generate the docs
- name: Commit and push changes
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add docs/ # assuming the docs are generated in a directory named "docs"
git commit -m "Generate CLI documentation" -a || echo "No changes to commit"
git push
This workflow will run whenever you push to the main branch. It checks out your code, sets up Go, generates the documentation, and then commits and pushes any changes. If the documentation generation doesn't result in any changes, the commit step will be skipped.
Maybe like this? https://cli.github.com/manual/gh ... I want a documentation about all commands (that means all subdommands as well).
Todo
manpage
commandCopilot conversation
Q
do you kmow how I can generate a documentation for my go cobra cli app automatically? it should list all commands with all params similar to the --help command
A
Yes, Cobra provides a built-in way to generate documentation for your CLI application. You can generate man pages, markdown, or a bash completion script. Here's how you can generate markdown documentation:
First, you need to import the
doc
package from Cobra:Then, you can generate the documentation for your root command and all its subcommands:
This will generate a markdown file for each command in your CLI application, with a filename based on the command's name. The files will be placed in the directory specified as the second argument to
GenMarkdownTree
.Each markdown file will contain a description of the command, its usage, and its flags, similar to the output of the
--help
command.Q
can this doccumentation be generated in asciidoc?
A
Yes, Cobra also supports generating documentation in Asciidoc format. Here's how you can do it:
First, you need to import the
doc
package from Cobra:Then, you can generate the documentation for your root command and all its subcommands:
This will generate an Asciidoc file for each command in your CLI application, with a filename based on the command's name. The files will be placed in the directory specified as the second argument to
GenAsciidocTree
.Each Asciidoc file will contain a description of the command, its usage, and its flags, similar to the output of the
--help
command.Q
can I generate these docs from github actions workflow?
A
Yes, you can generate Cobra CLI documentation as part of a GitHub Actions workflow. Here's a basic example of how you might set up such a workflow:
This workflow will run whenever you push to the main branch. It checks out your code, sets up Go, generates the documentation, and then commits and pushes any changes. If the documentation generation doesn't result in any changes, the commit step will be skipped.