Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

requesting option to add COMMANDS section to man pages via GenManTree #680

Open
GodloveD opened this issue Apr 19, 2018 · 4 comments · May be fixed by #939
Open

requesting option to add COMMANDS section to man pages via GenManTree #680

GodloveD opened this issue Apr 19, 2018 · 4 comments · May be fixed by #939
Labels
area/docs-generation Generation of docs via Cobra triage/needs-triage Needs to be placed into a milestone or be closed by maintainers

Comments

@GodloveD
Copy link

GodloveD commented Apr 19, 2018 •
edited

First, thanks for developing cobra! It's very useful.

It would be great if GenManTree could produce man pages with a COMMANDS section that would list all of the sub-commands along with the Short: description. Maybe this could be an option enabled via something like this"

var someCmd = &cobra.Command{
    DisplayCommandsInManPage: true,
    ...
}

Although COMMANDS is not a canonical section (as listed in man man-pages), it is sometimes included for programs that follow a command subcommand structure. Some Linux examples include:

blockdev
busctl
dmsetup
gpg
kmod 
systemctl

Since cobra encourages a command subcommand structure, this feature seems like a very natural feature for cobra to support.
@eparis
Copy link
Collaborator

eparis commented Apr 20, 2018

It sounds like a great idea. Right now we just generate a See Also, right?

@GodloveD
Copy link
Author

Yes. afaik that is correct.

Seems like the code is probably already written too right? Because commands are displayed via help.

@orobardet orobardet linked a pull request Aug 29, 2019 that will close this issue
Open
@github-actions
Copy link

This issue is being marked as stale due to a long period of inactivity

@johnSchnake johnSchnake added the area/docs-generation Generation of docs via Cobra label Mar 28, 2022
@johnSchnake
Copy link
Collaborator

Similar to #681 (comment) but since you want this to be autogenerated for each different command it would have to be coded.

Has a PR up with a small conflict; I don't have strong feelings about the doc generation so I'll defer to others.

@johnSchnake johnSchnake added triage/needs-triage Needs to be placed into a milestone or be closed by maintainers and removed kind/stale labels Mar 28, 2022
hoshsadiq pushed a commit to zulucmd/zulu that referenced this issue Dec 31, 2022
@orobardet @hoshsadiq
Add a COMMANDS section to generated man pages
4ae5ade 
When a command has available sub-commands, the COMMANDS
man section is generated with the list of sub-commands, with
their name, short description, and the name of the dedicated
man page.

Merge spf13/cobra#939

Fixes spf13/cobra#680
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area/docs-generation Generation of docs via Cobra triage/needs-triage Needs to be placed into a milestone or be closed by maintainers
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add a COMMANDS section to generated man pages orobardet/cobra
3 participants
@GodloveD @eparis @johnSchnake