timetrace
timetrace copied to clipboard
Copy command reference into Go files, e.g. `list.go`
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
.
Hello! I was experimenting with this and Cobra's doc.GenMarkdownTree
. Here are some observations for your consideration:
-
It seems that where there's both
Short
andLong
, the cli help message will only display theLong
version. -
The auto generation script works and generates the Markdown documentation we desire. This is a sample cobra-generated
timetrace_delete_project.md
: -
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:
Is this desirable, or is there a way to configure Cobra to output the Short
message rather than Long
message in the cli?
@jwnpoh Maybe for .Short to appear in the docs, you might need to customize it.
@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?