Auto-Generate a Docs-Page / Manpage with information about all commands and flags available for allsourde2adoc

[sebastian-sommerfeld-io]

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:

err := doc.GenMarkdownTree(rootCmd, "./path/to/docs")
if err != nil {
    log.Fatal(err)
}

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:

err := doc.GenAsciidocTree(rootCmd, "./path/to/docs")
if err != nil {
    log.Fatal(err)
}

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.