Skip to content

Commit a7d97cc

Browse files
bhardestybhardesty
committed
OCM-19067 | refactor: add tool to generate docs
1 parent 4d16e01 commit a7d97cc

File tree

11 files changed

+693
-58
lines changed

11 files changed

+693
-58
lines changed

‎Makefile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,10 @@ e2e_test: install
123123
--focus-file tests/e2e/.* \
124124
$(NULL)
125125

126+
.PHONY: generate-docs
127+
generate-docs:
128+
go run ./tools/gendocs
129+
126130
# verifies changes to .goreleaser.yaml
127131
.PHONY: check-release-config
128132
check-release-config:

‎cmd/rosa/main.go‎

Lines changed: 2 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -23,37 +23,9 @@ import (
2323

2424
"github.com/spf13/cobra"
2525

26-
"github.com/openshift/rosa/cmd/attach"
27-
"github.com/openshift/rosa/cmd/completion"
28-
"github.com/openshift/rosa/cmd/config"
29-
"github.com/openshift/rosa/cmd/create"
30-
"github.com/openshift/rosa/cmd/describe"
31-
"github.com/openshift/rosa/cmd/detach"
32-
"github.com/openshift/rosa/cmd/dlt"
33-
"github.com/openshift/rosa/cmd/docs"
34-
"github.com/openshift/rosa/cmd/download"
35-
"github.com/openshift/rosa/cmd/edit"
36-
"github.com/openshift/rosa/cmd/grant"
37-
"github.com/openshift/rosa/cmd/hibernate"
38-
"github.com/openshift/rosa/cmd/initialize"
39-
"github.com/openshift/rosa/cmd/install"
40-
"github.com/openshift/rosa/cmd/link"
41-
"github.com/openshift/rosa/cmd/list"
42-
"github.com/openshift/rosa/cmd/login"
43-
"github.com/openshift/rosa/cmd/logout"
44-
"github.com/openshift/rosa/cmd/logs"
45-
"github.com/openshift/rosa/cmd/register"
46-
"github.com/openshift/rosa/cmd/resume"
47-
"github.com/openshift/rosa/cmd/revoke"
48-
"github.com/openshift/rosa/cmd/token"
49-
"github.com/openshift/rosa/cmd/uninstall"
50-
"github.com/openshift/rosa/cmd/unlink"
51-
"github.com/openshift/rosa/cmd/upgrade"
52-
"github.com/openshift/rosa/cmd/verify"
53-
"github.com/openshift/rosa/cmd/version"
54-
"github.com/openshift/rosa/cmd/whoami"
5526
"github.com/openshift/rosa/pkg/arguments"
5627
"github.com/openshift/rosa/pkg/color"
28+
"github.com/openshift/rosa/pkg/commands"
5729
"github.com/openshift/rosa/pkg/info"
5830
"github.com/openshift/rosa/pkg/reporter"
5931
versionUtils "github.com/openshift/rosa/pkg/version"
@@ -76,35 +48,7 @@ func init() {
7648
arguments.AddDebugFlag(fs)
7749

7850
// Register the subcommands:
79-
root.AddCommand(completion.Cmd)
80-
root.AddCommand(create.Cmd)
81-
root.AddCommand(describe.Cmd)
82-
root.AddCommand(dlt.Cmd)
83-
root.AddCommand(docs.Cmd)
84-
root.AddCommand(download.Cmd)
85-
root.AddCommand(edit.Cmd)
86-
root.AddCommand(grant.Cmd)
87-
root.AddCommand(list.Cmd)
88-
root.AddCommand(initialize.Cmd)
89-
root.AddCommand(install.Cmd)
90-
root.AddCommand(login.Cmd)
91-
root.AddCommand(logout.Cmd)
92-
root.AddCommand(logs.Cmd)
93-
root.AddCommand(register.Cmd)
94-
root.AddCommand(revoke.Cmd)
95-
root.AddCommand(uninstall.Cmd)
96-
root.AddCommand(upgrade.Cmd)
97-
root.AddCommand(verify.Cmd)
98-
root.AddCommand(version.NewRosaVersionCommand())
99-
root.AddCommand(whoami.Cmd)
100-
root.AddCommand(hibernate.GenerateCommand())
101-
root.AddCommand(resume.GenerateCommand())
102-
root.AddCommand(link.Cmd)
103-
root.AddCommand(unlink.Cmd)
104-
root.AddCommand(token.Cmd)
105-
root.AddCommand(config.Cmd)
106-
root.AddCommand(attach.NewRosaAttachCommand())
107-
root.AddCommand(detach.NewRosaDetachCommand())
51+
commands.RegisterCommands(root)
10852
}
10953

11054
func main() {

‎codecov.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,5 @@ ignore:
1818
- "assets"
1919
- "hack"
2020
- "templates"
21+
- "tools"
2122
- "vendor"

‎pkg/commands/commands_suite_test.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package commands
2+
3+
import (
4+
"testing"
5+
6+
. "github.com/onsi/ginkgo/v2"
7+
. "github.com/onsi/gomega"
8+
)
9+
10+
func TestCommands(t *testing.T) {
11+
RegisterFailHandler(Fail)
12+
RunSpecs(t, "Commands Suite")
13+
}

‎pkg/commands/registry.go‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/*
2+
Copyright (c) 2020 Red Hat, Inc.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package commands
18+
19+
import (
20+
"github.com/spf13/cobra"
21+
22+
"github.com/openshift/rosa/cmd/attach"
23+
"github.com/openshift/rosa/cmd/completion"
24+
"github.com/openshift/rosa/cmd/config"
25+
"github.com/openshift/rosa/cmd/create"
26+
"github.com/openshift/rosa/cmd/describe"
27+
"github.com/openshift/rosa/cmd/detach"
28+
"github.com/openshift/rosa/cmd/dlt"
29+
"github.com/openshift/rosa/cmd/docs"
30+
"github.com/openshift/rosa/cmd/download"
31+
"github.com/openshift/rosa/cmd/edit"
32+
"github.com/openshift/rosa/cmd/grant"
33+
"github.com/openshift/rosa/cmd/hibernate"
34+
"github.com/openshift/rosa/cmd/initialize"
35+
"github.com/openshift/rosa/cmd/install"
36+
"github.com/openshift/rosa/cmd/link"
37+
"github.com/openshift/rosa/cmd/list"
38+
"github.com/openshift/rosa/cmd/login"
39+
"github.com/openshift/rosa/cmd/logout"
40+
"github.com/openshift/rosa/cmd/logs"
41+
"github.com/openshift/rosa/cmd/register"
42+
"github.com/openshift/rosa/cmd/resume"
43+
"github.com/openshift/rosa/cmd/revoke"
44+
"github.com/openshift/rosa/cmd/token"
45+
"github.com/openshift/rosa/cmd/uninstall"
46+
"github.com/openshift/rosa/cmd/unlink"
47+
"github.com/openshift/rosa/cmd/upgrade"
48+
"github.com/openshift/rosa/cmd/verify"
49+
"github.com/openshift/rosa/cmd/version"
50+
"github.com/openshift/rosa/cmd/whoami"
51+
)
52+
53+
// RegisterCommands registers all ROSA CLI subcommands to the provided root command.
54+
// This function provides a single source of truth for command registration, used by both
55+
// the main ROSA CLI (cmd/rosa/main.go) and the documentation generation tool
56+
// (tools/gendocs/gen_rosa_docs.go), ensuring docs stay in sync with the actual CLI.
57+
func RegisterCommands(root *cobra.Command) {
58+
root.AddCommand(completion.Cmd)
59+
root.AddCommand(create.Cmd)
60+
root.AddCommand(describe.Cmd)
61+
root.AddCommand(dlt.Cmd)
62+
root.AddCommand(docs.Cmd)
63+
root.AddCommand(download.Cmd)
64+
root.AddCommand(edit.Cmd)
65+
root.AddCommand(grant.Cmd)
66+
root.AddCommand(list.Cmd)
67+
root.AddCommand(initialize.Cmd)
68+
root.AddCommand(install.Cmd)
69+
root.AddCommand(login.Cmd)
70+
root.AddCommand(logout.Cmd)
71+
root.AddCommand(logs.Cmd)
72+
root.AddCommand(register.Cmd)
73+
root.AddCommand(revoke.Cmd)
74+
root.AddCommand(uninstall.Cmd)
75+
root.AddCommand(upgrade.Cmd)
76+
root.AddCommand(verify.Cmd)
77+
root.AddCommand(version.NewRosaVersionCommand())
78+
root.AddCommand(whoami.Cmd)
79+
root.AddCommand(hibernate.GenerateCommand())
80+
root.AddCommand(resume.GenerateCommand())
81+
root.AddCommand(link.Cmd)
82+
root.AddCommand(unlink.Cmd)
83+
root.AddCommand(token.Cmd)
84+
root.AddCommand(config.Cmd)
85+
root.AddCommand(attach.NewRosaAttachCommand())
86+
root.AddCommand(detach.NewRosaDetachCommand())
87+
}

‎pkg/commands/registry_test.go‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
package commands
2+
3+
import (
4+
. "github.com/onsi/ginkgo/v2"
5+
. "github.com/onsi/gomega"
6+
"github.com/spf13/cobra"
7+
)
8+
9+
var _ = Describe("RegisterCommands", func() {
10+
var rootCmd *cobra.Command
11+
12+
BeforeEach(func() {
13+
// Create a fresh root command for each test
14+
rootCmd = &cobra.Command{
15+
Use: "test",
16+
Short: "Test command",
17+
Long: "Test command for verifying command registration",
18+
}
19+
})
20+
21+
Context("when registering all ROSA CLI commands", func() {
22+
It("successfully registers all expected commands", func() {
23+
// Call the function under test
24+
RegisterCommands(rootCmd)
25+
26+
// Verify commands were registered
27+
commands := rootCmd.Commands()
28+
Expect(commands).ToNot(BeEmpty())
29+
30+
// Verify the expected number of commands are registered
31+
// As of this test, there should be 29 top-level commands
32+
Expect(len(commands)).To(Equal(29))
33+
34+
// Verify specific critical commands are present
35+
commandNames := make(map[string]bool)
36+
for _, cmd := range commands {
37+
commandNames[cmd.Name()] = true
38+
}
39+
40+
// Check for essential commands
41+
expectedCommands := []string{
42+
"completion",
43+
"create",
44+
"describe",
45+
"delete",
46+
"docs",
47+
"download",
48+
"edit",
49+
"grant",
50+
"list",
51+
"init",
52+
"install",
53+
"login",
54+
"logout",
55+
"logs",
56+
"register",
57+
"revoke",
58+
"uninstall",
59+
"upgrade",
60+
"verify",
61+
"version",
62+
"whoami",
63+
"hibernate",
64+
"resume",
65+
"link",
66+
"unlink",
67+
"token",
68+
"config",
69+
"attach",
70+
"detach",
71+
}
72+
73+
for _, cmdName := range expectedCommands {
74+
Expect(commandNames[cmdName]).To(BeTrue(), "Expected command '%s' to be registered", cmdName)
75+
}
76+
})
77+
78+
It("does not modify the root command's basic properties", func() {
79+
originalUse := rootCmd.Use
80+
originalShort := rootCmd.Short
81+
originalLong := rootCmd.Long
82+
83+
RegisterCommands(rootCmd)
84+
85+
// Verify root command properties remain unchanged
86+
Expect(rootCmd.Use).To(Equal(originalUse))
87+
Expect(rootCmd.Short).To(Equal(originalShort))
88+
Expect(rootCmd.Long).To(Equal(originalLong))
89+
})
90+
91+
It("can be called multiple times without error", func() {
92+
// First registration
93+
RegisterCommands(rootCmd)
94+
firstCount := len(rootCmd.Commands())
95+
96+
// Create a new root command for second registration
97+
rootCmd2 := &cobra.Command{
98+
Use: "test2",
99+
Short: "Test command 2",
100+
Long: "Test command 2 for verifying command registration",
101+
}
102+
103+
// Second registration on different root
104+
RegisterCommands(rootCmd2)
105+
secondCount := len(rootCmd2.Commands())
106+
107+
// Both should have the same number of commands
108+
Expect(firstCount).To(Equal(secondCount))
109+
Expect(firstCount).To(Equal(29))
110+
})
111+
})
112+
})

‎templates/clibyexample/template‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// NOTE: The contents of this file are auto-generated
2+
:_mod-docs-content-type: REFERENCE
3+
[id="rosa-cli-commands_{context}"]
4+
= ROSA CLI commands
5+
6+
{{range .Items}}
7+
8+
== {{.FullName}}
9+
{{.Description}}
10+
11+
.Example usage
12+
[source,bash,options="nowrap"]
13+
----
14+
{{.Examples}}
15+
----
16+
17+
{{end}}

‎tools/gendocs/gen_rosa_docs.go‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/*
2+
Copyright (c) 2020 Red Hat, Inc.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package main
18+
19+
import (
20+
"fmt"
21+
"os"
22+
23+
"github.com/spf13/cobra"
24+
25+
"github.com/openshift/rosa/pkg/commands"
26+
"github.com/openshift/rosa/tools/gendocs/gendocs"
27+
)
28+
29+
func main() {
30+
// Initialize the root command with all subcommands
31+
root := &cobra.Command{
32+
Use: "rosa",
33+
Short: "Command line tool for ROSA.",
34+
Long: "Command line tool for Red Hat OpenShift Service on AWS.\n" +
35+
"For further documentation visit " +
36+
"https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws\n",
37+
}
38+
39+
// Register all subcommands using shared function from pkg/commands
40+
commands.RegisterCommands(root)
41+
42+
// Generate the documentation
43+
outputFile := "docs/generated/rosa-by-example-content.adoc"
44+
if err := gendocs.GenDocs(root, outputFile); err != nil {
45+
fmt.Fprintf(os.Stderr, "Failed to generate documentation: %v\n", err)
46+
os.Exit(1)
47+
}
48+
49+
fmt.Printf("Documentation generated successfully: %s\n", outputFile)
50+
}

0 commit comments

Comments
 (0)