timetrace icon indicating copy to clipboard operation
timetrace copied to clipboard

Copy command reference into Go files, e.g. `list.go`

Open dominikbraun opened this issue 3 years ago • 3 comments

The goal of #84 was to find a way to auto-generate documentation out of the Cobra commands. @obnoxiousnerd found a simple way to do this natively with Cobra. Thanks!

As a next step, the command references from README.md should me copied into the Cobra commands. Each Cobra command has a Long field for long help texts, and the existing documentation should be moved into that field.

Ideally, as a result, generating the documentation from the commands should produce the same output as the current Markdown documentation in README.md.

dominikbraun avatar May 27 '21 10:05 dominikbraun

Hello! I was experimenting with this and Cobra's doc.GenMarkdownTree. Here are some observations for your consideration:

  1. It seems that where there's both Short and Long, the cli help message will only display the Long version.

  2. The auto generation script works and generates the Markdown documentation we desire. This is a sample cobra-generated timetrace_delete_project.md: image

  3. However this requires that the Markdown annotations go directly into the string for the Long field of the Cobra command. This results in the cli output like so: image

Is this desirable, or is there a way to configure Cobra to output the Short message rather than Long message in the cli?

jwnpoh avatar Jul 04 '21 17:07 jwnpoh

@jwnpoh Maybe for .Short to appear in the docs, you might need to customize it.

retronav avatar Jul 04 '21 17:07 retronav

@obnoxiousnerd I'm not sure if the intention is to include both .Short and .Long in the docs. My understanding of this issue is that @dominikbraun was hoping that populating .Long in the code itself can facilitate easier updating of docs when the different functions of the app gets updated.

Please correct me if I'm wrong?

jwnpoh avatar Jul 05 '21 01:07 jwnpoh