Making initCompleteCmd exported so completion commands can be documented

[gssbzn]

Right now if you try to generate documentation the usual way

package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	err := doc.GenReSTTree(cmd, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}

Will not generate docs for the auto generated completion command, an alternative to get it to work would be to alter the example to

package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}

	_, _ = cmd.ExecuteC() // init completion command indirectly

	err := doc.GenReSTTree(cmd, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}

but this will cause to init the help command which the current behaviour (I believe) is ok on not documenting

Is there any reasons why initCompleteCmd is not exported and could we make it so so I can replace _, _ = cmd.ExecuteC() with a call to just that function when documenting commands? InitDefaultHelpCmd seems to be exported so we would be aligning with that behaviour

Happy to make a PR if this is ok to change

Edit: this condition

cobra/doc/rest_docs.go

Line 146 in de187e8

if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {

will prevent help from being documented but I still there's value on exporting initCompleteCmd to make this more focused to what's needed

[marckhouzam]

Hi @gssbzn. I am not too familiar with the REST generation provided by Cobra. If I try calling doc. GenReSTTree() from a sub-command of my program, then the "completion" command is properly documented. But that is because the Execute() function is called in that usecase.

I realize the Cobra documentation gives examples of REST generation that don't use Execute(), however, is this a valid scenario for you, or are you just trying the examples?

That being said, if we need to support generating REST without calling Execute(), I think you are right:
1- we'll need to make public InitDefaultCompletionCmd() (not initCompleteCmd() which sets up the hidden __complete command).
2- add a call to this new public function here:

cobra/doc/rest_docs.go

Line 63 in de187e8

cmd.InitDefaultHelpFlag()

Finally, you should know that the "completion" command is not created if there are no subcommands, so even with the above changes, I don't believe the example will include the "completion" command; you'd have to create a subcommand first.

[gssbzn]

Hi @marckhouzam thanks for looking into this, so expanding to a more complete example, the one I gave was basically from the docs but we've been documenting our commands before, completion included as we used to do it manually but since the change to the dynamic ones introduced in the latest cobra and now those files are no longer generated.

Full example

cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	subcmd := &cobra.Command{
		Use:   "sub-test",
		Short: "my test command",
		Run: func(cmd *cobra.Command, args []string) {
			log.Println("test")
		},
	}
	cmd.AddCommand(subcmd)

	if err := doc.GenReSTTree(cmd, "./docs/command"); err != nil {
		log.Fatal(err)
	}

it will only generate the test.rst and test_sub-test.rst files, changing to doc.GenReSTTree(subcmd, "./docs/command") only generates test_sub-test.rst

Explicitly calling _ = cmd.Execute() before doc.GenReSTTree(cmd, "./docs/command"); generates the full completion command docs

I think I'll go ahead and make initDefaultCompletionCmd public and document this behaviour better

[github-actions]

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

[lowdewijk]

I'd also like initDefaultCompletionCmd to be exported. The problem I am having is that I have some small alterations I want to do, which are impossible when this function is not exported.

I have done the same to the help command, which was possible, because InitDefaultHelpCmd is exported.

For reference the alterations I want to do:

• Start the short message with a lowercase instead of uppercase character (this is part of our style guide)
• I have placed all cli related commands under acli sub-command and I would like to move completions to it. So I would like it to be mycli cli completions instead of mycli completions.