dominikbraun / timetrace

A simple CLI for tracking your working time.
Apache License 2.0
700 stars 76 forks source link

Look for a way to auto-generate documentation for commands #84

Closed dominikbraun closed 3 years ago

dominikbraun commented 3 years ago

I'd love to auto-generate the documentation for commands from the cobra.Command.Long help text and the command's options. Maybe there's some cool way to do this?

retronav commented 3 years ago

Cobra includes command generation. Here are the docs: https://github.com/spf13/cobra/blob/master/doc/README.md https://github.com/spf13/cobra/blob/master/doc/md_docs.md

I will definitely play with that a bit and get back here!

retronav commented 3 years ago

I tried generating some docs, and it works:

Generated docs:

  1. Index documentation image

  2. Document of a command image

  3. Documentation of a subcommand image

Steps to generate documentation

  1. Create a script file (in a separate directory)
  2. Paste the main function from main.go, but with some modifications
    
    package main

import ( "log"

"github.com/dominikbraun/timetrace/cli"
"github.com/dominikbraun/timetrace/config"
"github.com/dominikbraun/timetrace/core"
"github.com/dominikbraun/timetrace/fs"
"github.com/dominikbraun/timetrace/out"
"github.com/spf13/cobra/doc"

)

var version = "UNDEFINED"

func main() { c, err := config.FromFile() if err != nil { out.Warn("%s", err.Error()) }

filesystem := fs.New(c)
timetrace := core.New(c, filesystem)

cmd := cli.RootCommand(timetrace, version)
err = doc.GenMarkdownTree(cmd, "./docs")
if err != nil {
    log.Fatal(err)
}

}


3. Running that script with `go run` places docs in the `docs` directory in cwd

This was the process. We can incorporate it in CI with a bit of refining. @dominikbraun Any suggestions? 
dominikbraun commented 3 years ago

Wow, thanks! This looks exactly like what I've been looking for. I'm going to open some issues for implementing this 😄

dominikbraun commented 3 years ago

I'm going to close this since we found a way to auto-generate docs. The subsequent issue is #87. Thanks again for figuring this out!