This patch modifies the GenMarkdownCustom to skip writing a Synopsis
header with the `cmd.Short` duplicated both before and after the header.
Instead, it only writes the `### Synopsis` header and the paragraph when
a `cmd.Long` has some kind of content in it.
Adds `TestGenMdDocWithNoLongOrSynopsis` as the test case.
Signed-off-by: Marc Lopez <marc5.12@outlook.com>
Previously if a cobra user didn't specify an explicit .Date header, the
current time would be included in all of the generated man pages each
time they were built. This causes an issue for reproducible builds,
since each re-build of a package that includes the man pages will have
different times listed in the man pages.
To fix this, add support for SOURCE_DATE_EPOCH (which is a standardised
packaging environment variable, designed to be used specifically for
this purpose[1]).
[1]: https://reproducible-builds.org/specs/source-date-epoch/
Signed-off-by: Aleksa Sarai <asarai@suse.de>
benchmark old ns/op new ns/op delta
BenchmarkGenYamlToFile-4 62488 61622 -1.39%
benchmark old allocs new allocs delta
BenchmarkGenYamlToFile-4 121 120 -0.83%
benchmark old bytes new bytes delta
BenchmarkGenYamlToFile-4 26706 26280 -1.60%
The default pflag error is to only print the bad flag. This enables an application
to include a usage message or other details about the error.
Signed-off-by: Daniel Nephin <dnephin@gmail.com>
* Moving final return outside of if-else
* Removing type declarations that Go can infer from values
* Cleaning up some existing comments
* Changing snake_case variables to camelCase
Just like the last commit, but now for manpages.
genMan still works with a buffer and returns []byte instead of working
directly with an io.Writer. This is because, in turn, md2man takes byte
slices instead of readers and writers.
Wrapping genMan around a writer is unnecessary especially since it's not
an exported function, and also because we'd still need a buffer to get
the output bytes.
This code was already using io.Writer, but was completely ignoring write
errors.
The most worrying part is how GenMarkdownTreeCustom used an unnecessary
buffer to then dump all of its contents on a file, and instead of
returning an error on file creation/writing, it would just exit the
entire program.
* Move man_docs and md_docs into new doc pkg
* Replace *bytes.Buffer with io.Writer
* Replace c == cmd.helpCommand with c.IsHelpCommand()
* Remove redundant len(children) == 0 check in HasSeeAlso
* Duplicate test setup for doc generation
