Add more help documentation, automatically generate CLI reference #471
Conversation
cdrage
commented
May 23, 2018
cdrage
commented
- Adds more help documentation
- Adds script to generate CLI reference
cdrage
changed the title
cdrage
added
the
do-not-merge/work-in-progress
|
Still need to add a lot more documentation. But this is my progress so far. |
cdrage
force-pushed
the
generate-docs
branch
12 times, most recently
from
f687d98 to
6710e87
Compare
cdrage
changed the title
cdrage
removed
the
do-not-merge/work-in-progress
|
Ready for review @kadel Mainly, look at the structure here: https://github.com/cdrage/odo/blob/6710e871e39054b5aa607f55e234de78a969db4e/docs/cli-reference.md All the other "fluff" in the code is simple edits to |
There was a problem hiding this comment.
Great work @cdrage. This improves our docs and cli help a lot.
I've just added a few comments to descriptions that might be a little bit confusing. But in general, it looks good.
On small thing. The tests are failing because you have two main functions in the same package (in generate-cli-structure.go and in generate-cli-reference.go).
This can be easily solved if you put those files into the separate folder. For example into scripts/cli-reference/ and scripts/cli-structure/.
cmd/root.go
Outdated
| Short: "OpenShift CLI for Developers", | ||
| Long: `OpenShift CLI for Developers`, | ||
| Short: "Odo (Openshift Do)", | ||
| Long: `Odo (OpenShift Do) is a CLI tool for running OpenShift applications in a fast and automated matter. Odo reduces the complexity of deployment by adding continuous development without the worry of deploying your source code. |
There was a problem hiding this comment.
I'm not sure about the phrase "continuous development".
"Iterative development" might be better I think.
cmd/storage.go
Outdated
| @@ -3,12 +3,13 @@ package cmd | |||
| import ( | |||
| "fmt" | |||
|
|
|||
cmd/component.go
Outdated
| @@ -36,7 +33,10 @@ var componentGetCmd = &cobra.Command{ | |||
| Use: "get", | |||
| Short: "Get currently active component", | |||
| Long: "Get currently active component.", | |||
| Args: cobra.NoArgs, | |||
| Example: ` # Get the currently active component | |||
| odo get | |||
There was a problem hiding this comment.
There is a word component missing in the command (should be odo component get)
cmd/storage.go
Outdated
| Args: cobra.ExactArgs(1), | ||
| Short: "Delete storage from component", | ||
| Example: ` # Delete storage from component 'mongodb' | ||
| odo storage delete --component mongodb |
There was a problem hiding this comment.
This command is not valid. odo storage delete requires storage name as an argument.
odo storage delete mystorage --component mongodb - Delete 'mystroage' from 'mongodb' component.
cmd/storage.go
Outdated
| Args: cobra.MaximumNArgs(1), | ||
| Short: "List storage attached to a component", | ||
| Long: "List storage attached to a component", | ||
| Example: ` # List all attached storage |
There was a problem hiding this comment.
odo storage list lists storage attached/mounted to the current component and all unattached/unmounted storage in the current application.
cmd/url.go
Outdated
| odo url create | ||
|
|
||
| # Create a URL for a specific component | ||
| odo url create <component name> |
There was a problem hiding this comment.
This is an example, instead of <component name> there should be example component name
cmd/url.go
Outdated
| `, | ||
| Long: `Delete the given URL, hence making the service inaccessible.`, | ||
| Example: ` # Delete a URL to a component | ||
| odo url delete <URL> |
There was a problem hiding this comment.
This is an example, instead of there should be url name.
(right now URLs have the same name as the components)
cdrage
force-pushed
the
generate-docs
branch
4 times, most recently
from
7887a18 to
5dc1ed0
Compare
|
@kadel Updated. Ready for another review / merge 👍 |
cmd/url.go
Outdated
| odo url create | ||
|
|
||
| # Create a URL for a specific component | ||
| odo url create myurl |
There was a problem hiding this comment.
myurl might be a bit misleading. The argument is a name of a component. This looks like it is a name of an url.
mycomponent might be better
| `, | ||
| Long: `Delete the given URL, hence making the service inaccessible.`, | ||
| Example: ` # Delete a URL to a component | ||
| odo url delete myurl |
There was a problem hiding this comment.
here is myurl ok, as delete has URL name as an argument.
- Adds more help documentation - Adds script to generate CLI reference
|
@kadel Updated! |
