Man pages won't have auto gen tag when option is disabled (#1104)

* Man pages wont have  auto gen tag when option is disabled

- this addresses #741

* Add documentation for doc generation and a changelog
This commit is contained in:
John McBride 2020-04-29 11:15:55 -06:00 committed by GitHub
parent 41fd44e1df
commit e392f3204d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 40 additions and 8 deletions

22
CHANGELOG.md Normal file
View file

@ -0,0 +1,22 @@
# Cobra Changelog
## Pending
* Fix man page doc generation - no auto generated tag when `cmd.DisableAutoGenTag = true` @jpmcb
## v1.0.0
Announcing v1.0.0 of Cobra. 🎉
**Notable Changes**
* Fish completion (including support for Go custom completion) @marckhouzam
* API (urgent): Rename BashCompDirectives to ShellCompDirectives @marckhouzam
* Remove/replace SetOutput on Command - deprecated @jpmcb
* add support for autolabel stale PR @xchapter7x
* Add Labeler Actions @xchapter7x
* Custom completions coded in Go (instead of Bash) @marckhouzam
* Partial Revert of #922 @jharshman
* Add Makefile to project @jharshman
* Correct documentation for InOrStdin @desponda
* Apply formatting to templates @jharshman
* Revert change so help is printed on stdout again @marckhouzam
* Update md2man to v2.0.0 @pdf
* update viper to v1.4.0 @umarcor
* Update cmd/root.go example in README.md @jharshman

View file

@ -718,11 +718,7 @@ Run 'kubectl help' for usage.
## Generating documentation for your command ## Generating documentation for your command
Cobra can generate documentation based on subcommands, flags, etc. in the following formats: Cobra can generate documentation based on subcommands, flags, etc. Read more about it in the [docs generation documentation](doc/README.md).
- [Markdown](doc/md_docs.md)
- [ReStructured Text](doc/rest_docs.md)
- [Man Page](doc/man_docs.md)
## Generating bash completions ## Generating bash completions

12
doc/README.md Normal file
View file

@ -0,0 +1,12 @@
# Documentation generation
- [Man page docs](./man_docs.md)
- [Markdown docs](./md_docs.md)
- [Rest docs](./rest_docs.md)
- [Yaml docs](./yaml_docs.md)
## Options
### `DisableAutoGenTag`
You may set `cmd.DisableAutoGenTag = true`
to _entirely_ remove the auto generated string "Auto generated by spf13/cobra..."
from any documentation source.

View file

@ -105,7 +105,7 @@ func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error {
if header == nil { if header == nil {
header = &GenManHeader{} header = &GenManHeader{}
} }
if err := fillHeader(header, cmd.CommandPath()); err != nil { if err := fillHeader(header, cmd.CommandPath(), cmd.DisableAutoGenTag); err != nil {
return err return err
} }
@ -114,7 +114,7 @@ func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error {
return err return err
} }
func fillHeader(header *GenManHeader, name string) error { func fillHeader(header *GenManHeader, name string, disableAutoGen bool) error {
if header.Title == "" { if header.Title == "" {
header.Title = strings.ToUpper(strings.Replace(name, " ", "\\-", -1)) header.Title = strings.ToUpper(strings.Replace(name, " ", "\\-", -1))
} }
@ -133,7 +133,7 @@ func fillHeader(header *GenManHeader, name string) error {
header.Date = &now header.Date = &now
} }
header.date = (*header.Date).Format("Jan 2006") header.date = (*header.Date).Format("Jan 2006")
if header.Source == "" { if header.Source == "" && !disableAutoGen {
header.Source = "Auto generated by spf13/cobra" header.Source = "Auto generated by spf13/cobra"
} }
return nil return nil

View file

@ -101,6 +101,8 @@ func TestGenManNoGenTag(t *testing.T) {
unexpected := translate("#HISTORY") unexpected := translate("#HISTORY")
checkStringOmits(t, output, unexpected) checkStringOmits(t, output, unexpected)
unexpected = translate("Auto generated by spf13/cobra")
checkStringOmits(t, output, unexpected)
} }
func TestGenManSeeAlso(t *testing.T) { func TestGenManSeeAlso(t *testing.T) {