search

dominikbraun / timetrace

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

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

Open dominikbraun opened 3 years ago

dominikbraun commented 3 years ago

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.

jwnpoh commented 3 years ago

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?

retronav commented 3 years ago

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

jwnpoh commented 3 years ago

@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?