[#38] Add end-user documentation to project

1. Add end-user documentation of CLI commands
2. Minor refactor of several help messages
3. Update of golden test data to reflect help message changes

Change-Id: I58b8ac3a7871efdb569887ab65191bfb1842c24e
Signed-off-by: Alexander Hughes <Alexander.Hughes@pm.me>

cmd/cluster/initinfra.go

@@ -53,7 +53,7 @@ func addInitinfraFlags(i *initinfra.Infra, cmd *cobra.Command) {
 		&i.DryRun,
 		"dry-run",
 		false,
-		"Don't deliver documents to the cluster, see the changes instead")
+		"Don't deliver documents to the cluster, simulate the changes instead")
 
 	flags.BoolVar(
 		&i.Prune,
@@ -66,6 +66,6 @@ func addInitinfraFlags(i *initinfra.Infra, cmd *cobra.Command) {
 		&i.ClusterType,
 		"cluster-type",
 		"ephemeral",
-		`Select cluster type to be deploy initial infastructure to,`+
+		`Select cluster type to deploy initial infastructure to;`+
 			` currently only ephemeral is supported`)
 }

cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden

@@ -8,7 +8,7 @@ Examples:
 	airshipctl cluster initinfra
 
 Flags:
-      --cluster-type string   Select cluster type to be deploy initial infastructure to, currently only ephemeral is supported (default "ephemeral")
+      --cluster-type string   Select cluster type to deploy initial infastructure to; currently only ephemeral is supported (default "ephemeral")
-      --dry-run               Don't deliver documents to the cluster, see the changes instead
+      --dry-run               Don't deliver documents to the cluster, simulate the changes instead
   -h, --help                  help for initinfra
       --prune                 If set to true, command will delete all kubernetes resources that are not defined in airship documents and have airshipit.org/deployed=initinfra label

cmd/completion/completion.go

@@ -8,9 +8,9 @@ import (
 )
 
 const completionDesc = `
-Generate autocompletions script for airshipctl for the specified shell (bash or zsh).
+Generate autocompletion script for airshipctl for the specified shell (bash or zsh).
 
-This command can generate shell autocompletions. e.g.
+This command can generate shell autocompletion. e.g.
 
 	$ airshipctl completion bash
 

cmd/config/get_authinfo.go

@@ -24,13 +24,13 @@ import (
 )
 
 var (
-	getAuthInfoLong = `Display a specific user information, or all defined users if no name is provided`
+	getAuthInfoLong = `Display a specific user's information, or all defined users if no name is provided`
 
 	getAuthInfoExample = `# List all the users airshipctl knows about
-airshipctl config get-credential
+airshipctl config get-credentials
 
 # Display a specific user information
-airshipctl config get-credential e2e`
+airshipctl config get-credentials e2e`
 )
 
 // An AuthInfo refers to a particular user for a cluster

cmd/config/set_authinfo.go

@@ -27,23 +27,8 @@ import (
 
 var (
 	setAuthInfoLong = fmt.Sprintf(`Sets a user entry in airshipctl config
-Specifying a name that already exists will merge new fields on top of existing values.
+Specifying a name that already exists will merge new fields on top of existing values.`,
-
+	)
-Client-certificate flags:
---%v=certfile --%v=keyfile
-
-Bearer token flags:
---%v=bearer_token
-
-Basic auth flags:
---%v=basic_user --%v=basic_password
-
-Bearer token and basic auth are mutually exclusive.`,
-		config.FlagCertFile,
-		config.FlagKeyFile,
-		config.FlagBearerToken,
-		config.FlagUsername,
-		config.FlagPassword)
 
 	setAuthInfoExample = fmt.Sprintf(`
 # Set only the "client-key" field on the "cluster-admin"
@@ -112,19 +97,19 @@ func addSetAuthInfoFlags(o *config.AuthInfoOptions, cmd *cobra.Command) {
 		&o.Token,
 		config.FlagBearerToken,
 		"",
-		config.FlagBearerToken+" for the user entry in airshipctl")
+		config.FlagBearerToken+" for the user entry in airshipctl. Mutually exclusive with username and password flags.")
 
 	flags.StringVar(
 		&o.Username,
 		config.FlagUsername,
 		"",
-		config.FlagUsername+" for the user entry in airshipctl")
+		config.FlagUsername+" for the user entry in airshipctl. Mutually exclusive with token flag.")
 
 	flags.StringVar(
 		&o.Password,
 		config.FlagPassword,
 		"",
-		config.FlagPassword+" for the user entry in airshipctl")
+		config.FlagPassword+" for the user entry in airshipctl. Mutually exclusive with token flag.")
 
 	flags.BoolVar(
 		&o.EmbedCertData,

cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden

@@ -19,7 +19,7 @@ Flags:
       --client-key string           Path to client-key file for the user entry in airshipctl
       --embed-certs                 Embed client cert/key for the user entry in airshipctl
   -h, --help                        help for set-credentials
-      --password string             password for the user entry in airshipctl
+      --password string             password for the user entry in airshipctl. Mutually exclusive with token flag.
-      --token string                token for the user entry in airshipctl
+      --token string                token for the user entry in airshipctl. Mutually exclusive with username and password flags.
-      --username string             username for the user entry in airshipctl
+      --username string             username for the user entry in airshipctl. Mutually exclusive with token flag.
 

cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden

@@ -19,7 +19,7 @@ Flags:
       --client-key string           Path to client-key file for the user entry in airshipctl
       --embed-certs                 Embed client cert/key for the user entry in airshipctl
   -h, --help                        help for set-credentials
-      --password string             password for the user entry in airshipctl
+      --password string             password for the user entry in airshipctl. Mutually exclusive with token flag.
-      --token string                token for the user entry in airshipctl
+      --token string                token for the user entry in airshipctl. Mutually exclusive with username and password flags.
-      --username string             username for the user entry in airshipctl
+      --username string             username for the user entry in airshipctl. Mutually exclusive with token flag.
 

cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden

@@ -1,17 +1,6 @@
 Sets a user entry in airshipctl config
 Specifying a name that already exists will merge new fields on top of existing values.
 
-Client-certificate flags:
---client-certificate=certfile --client-key=keyfile
-
-Bearer token flags:
---token=bearer_token
-
-Basic auth flags:
---username=basic_user --password=basic_password
-
-Bearer token and basic auth are mutually exclusive.
-
 Usage:
   set-credentials NAME [flags]
 
@@ -32,6 +21,6 @@ Flags:
       --client-key string           Path to client-key file for the user entry in airshipctl
       --embed-certs                 Embed client cert/key for the user entry in airshipctl
   -h, --help                        help for set-credentials
-      --password string             password for the user entry in airshipctl
+      --password string             password for the user entry in airshipctl. Mutually exclusive with token flag.
-      --token string                token for the user entry in airshipctl
+      --token string                token for the user entry in airshipctl. Mutually exclusive with username and password flags.
-      --username string             username for the user entry in airshipctl
+      --username string             username for the user entry in airshipctl. Mutually exclusive with token flag.

cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden

@@ -4,10 +4,10 @@ Usage:
 
 Examples:
 # List all the users airshipctl knows about
-airshipctl config get-credential
+airshipctl config get-credentials
 
 # Display a specific user information
-airshipctl config get-credential e2e
+airshipctl config get-credentials e2e
 
 Flags:
   -h, --help   help for get-credentials

docs/source/cli/cli.rst

@@ -0,0 +1,545 @@
+..
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _airshipctl-cli:
+
+==============
+AirshipCTL CLI
+==============
+
+The AirshipCTL CLI is used in conjunction with the binary created by running ``make build``.  This binary, by default,
+is created in the ``airshipctl/bin/`` directory.
+
+
+CLI Options
+===========
+
+**-h / \\-\\-help**
+
+Prints help for a specific command or command group.
+
+**\\-\\-debug** (Optional, default: false)
+
+Enables verbose output of commands.
+
+**\\-\\-airshipconf** (Optional, default: `$HOME/.airship/config`)
+
+Path to file for airshipctl configuration.
+
+**\\-\\-kubeconfig** (Optional, default: `$HOME/.airship/kubeconfig`)
+
+Path to kubeconfig associated with airshipctl configuration.
+
+.. _root-group:
+
+Root Group
+==========
+
+Allows you to perform top level commands
+
+::
+
+  airshipctl <command>
+
+Version
+-------
+
+Output the version of the airshipctl binary.
+
+Usage:
+
+::
+
+    airshipctl version
+
+Completion
+----------
+
+Generate autocompletion script for airshipctl for the specified shell (bash or zsh).
+
+**shell** (Required)
+
+Shell to generate autocompletion script for.  Supported values are `bash` and `zsh`
+
+Usage:
+
+::
+
+    airshipctl completion <shell>
+
+Examples
+^^^^^^^^
+
+This command can generate bash autocompletion. e.g.
+
+::
+
+    $ airshipctl completion bash
+
+Which can be sourced as such:
+
+::
+
+    $ source <(airshipctl completion bash)
+
+.. _bootstrap-group:
+
+Bootstrap Group
+===============
+
+Used to bootstrap the ephemeral Kubernetes cluster.
+
+ISOgen
+-------
+
+Generate bootstrap ISO image.
+
+Usage:
+
+::
+
+    airshipctl bootstrap isogen
+
+RemoteDirect
+------------
+
+Bootstrap ephemeral node.
+
+Usage:
+
+::
+
+    airshipctl bootstrap remotedirect
+
+.. _cluster-group:
+
+Cluster Group
+=============
+
+Control Kubernetes cluster.
+
+InitInfra
+------------
+
+Deploy initinfra components to cluster.
+
+**cluster-type** (Optional, default:"ephemeral")
+
+Select cluster type to deploy initial infrastructure to, currently only ephemeral is supported.
+
+**\\-\\-dry-run** (Optional).
+
+Don't deliver documents to the cluster, simulate the changes instead.
+
+**\\-\\-prune** (Optional, default:false)
+
+If set to true, command will delete all kubernetes resources that are not defined in airship documents and have
+airshipit.org/deployed=initinfra label
+
+Usage:
+
+::
+
+    airshipctl cluster initinfra <flags>
+
+.. _config-group:
+
+Config Group
+============
+
+Modify airshipctl config files
+
+Get-Cluster
+-----------
+
+Display cluster information.
+
+**name** (Optional, default: all defined clusters)
+
+Displays a specific cluster if specified, or if left blank all defined clusters.
+
+**\\-\\-cluster-type** (Required).
+
+cluster-type for the cluster-entry in airshipctl config. Currently only ephemeral cluster types are supported.
+
+Usage:
+
+::
+
+    airshipctl config get-cluster <name> --cluster-type=<cluster-type>
+
+Examples
+^^^^^^^^
+
+List all the clusters airshipctl knows about:
+
+::
+
+    airshipctl config get-cluster
+
+Display a specific cluster:
+
+::
+
+    airshipctl config get-cluster e2e --cluster-type=ephemeral
+
+Get-Context
+-----------
+
+Displays context information
+
+**name** (Optional, default: all defined contexts)
+
+Displays a named context, if no name is provided display all defined contexts.
+
+**\\-\\-current-context** (Optional, default:false)
+
+Display the current context, supersedes the `name` argument.
+
+Usage:
+
+::
+
+    airshipctl config get-context
+
+Examples
+^^^^^^^^
+
+For all contexts:
+
+::
+
+    airshipctl config get-context
+
+For the current context:
+
+::
+
+    airshipctl config get-context --current
+
+For a named context:
+
+::
+
+    airshipctl config get-context e2e
+
+
+Get-Credentials
+---------------
+
+Display a user's information.
+
+**name** (Optional, default: all defined users)
+
+Display a specific user's information.  If no name is specified, list all defined users.
+
+Usage:
+
+::
+
+    airshipctl config get-credentials <NAME>
+
+Examples
+^^^^^^^^
+
+List all the users airshipctl knows about:
+
+::
+
+    airshipctl config get-credentials
+
+Display a specific user's information:
+
+::
+
+    airshipctl config get-credentials e2e
+
+Init
+----
+
+Generate initial configuration files for airshipctl
+
+Usage:
+
+::
+
+    airshipctl config init
+
+Set-Cluster
+-----------
+
+Sets a cluster entry in the airshipctl config.
+
+**name** (Required)
+
+The name of the cluster to add to airshipctl config.
+
+.. note::
+
+    Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
+**\\-\\-certificate-authority** (Optional)
+
+Path to certificate-authority file for the cluster entry in airshipctl config
+
+**\\-\\-certificate-authority** (Required)
+
+Cluster-type for the cluster entry in airshipctl config
+
+**\\-\\-embed-certs** (Optional)
+
+Embed-certs for the cluster entry in airshipctl config
+
+**\\-\\-insecure-skip-tls-verify** (Optional, default:true)
+
+Insecure-skip-tls-verify for the cluster entry in airshipctl config
+
+**\\-\\-server** (Optional)
+
+Server for the cluster entry in airshipctl config
+
+Usage:
+
+::
+
+    airshipctl config set-cluster <name> <flags>
+
+Examples
+^^^^^^^^
+
+Set only the server field on the e2e cluster entry without touching other values:
+
+::
+
+    airshipctl config set-cluster e2e --cluster-type=ephemeral --server=https://1.2.3.4
+
+Embed certificate authority data for the e2e cluster entry:
+
+::
+
+    airshipctl config set-cluster e2e --cluster-type=target --certificate-authority-authority=~/.airship/e2e/kubernetes.ca.crt
+
+Disable cert checking for the dev cluster entry:
+
+::
+
+    airshipctl config set-cluster e2e --cluster-type=target --insecure-skip-tls-verify=true
+
+Configure client certificate:
+
+::
+
+    airshipctl config set-cluster e2e --cluster-type=target --embed-certs=true --client-certificate=".airship/cert_file"
+
+Set-Context
+-----------
+
+Switch to a new context, or update context values in the airshipctl config
+
+**name** (Required)
+
+The name of the context to set.
+
+**\\-\\-cluster-string**
+
+Sets the cluster for the specified context in the airshipctl config.
+
+**\\-\\-cluster-type**
+
+Sets the cluster-type for the specified context in the airshipctl config.
+
+**\\-\\-current**
+
+Use current context from airshipctl config.
+
+**\\-\\-manifest**
+
+Sets the manifest for the specified context in the airshipctl config.
+
+**\\-\\-namespace**
+
+Sets the namespace for the specified context in the airshipctl config.
+
+**\\-\\-user**
+
+Sets the user for the specified context in the airshipctl config.
+
+Usage:
+
+::
+
+    airshipctl config set-context <name> <flags>
+
+Examples
+^^^^^^^^
+
+Create a completely new e2e context entry:
+
+::
+
+    airshipctl config set-context e2e --namespace=kube-system --manifest=manifest --user=auth-info --cluster-type=target
+
+Update the current-context to e2e:
+
+::
+
+    airshipctl config set-context e2e
+
+Update attributes of the current-context:
+
+::
+
+    airshipctl config set-context --current --manifest=manifest
+
+
+Set-Credentials
+---------------
+
+Sets a user entry in the airshipctl config.
+
+**name** (Required)
+
+The user entry to update in airshipctl config.
+
+.. note:: Specifying a name that already exists will merge new fields on top of existing values.
+
+**\\-\\-client-certificate**
+
+Path to client-certificate file for the user entry in airshipctl
+
+**\\-\\-client-key**
+
+Path to client-key file for the user entry in airshipctl
+
+**\\-\\-embed-certs**
+
+Embed client cert/key for the user entry in airshipctl
+
+**\\-\\-password**
+
+Password for the user entry in airshipctl
+
+.. note:: Username and Password flags are mutually exclusive with Token flag
+
+**\\-\\-token**
+
+Token for the user entry in airshipctl
+
+.. note:: Username and Password flags are mutually exclusive with Token flag
+
+**\\-\\-username**
+
+Username for the user entry in airshipctl
+
+.. note:: Username and Password flags are mutually exclusive with Token flag
+
+Usage:
+
+::
+
+    airshipctl config set-credentials <name> <flags>
+
+Examples
+^^^^^^^^
+
+Set only the "client-key" field on the "cluster-admin" entry, without touching other values:
+
+::
+
+    airshipctl config set-credentials cluster-admin --username=~/.kube/admin.key
+
+Set basic auth for the "cluster-admin" entry
+
+::
+
+    airshipctl config set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif
+
+Embed client certificate data in the "cluster-admin" entry
+
+::
+
+    airshipctl config set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true
+
+.. _document-group:
+
+Document Group
+==============
+
+Manages deployment documents.
+
+Pull
+----
+
+Pulls documents from remote git repository.
+
+Usage:
+
+::
+
+    airshipctl document pull
+
+Render
+------
+
+Render documents from model.
+
+**-a / \\-\\-annotation**
+
+Filter documents by Annotations.
+
+**-g / \\-\\-apiversion**
+
+Filter documents by API version.
+
+**-f / \\-\\-filter**
+
+Logical expression for document filtering.
+
+**-k / \\-\\-kind**
+
+Filter documents by Kinds.
+
+**-l / \\-\\-label**
+
+Filter documents by Labels.
+
+Usage:
+
+::
+
+    airshipctl document render <flags>
+
+.. _secret-group:
+
+Secret Group
+============
+
+Manages secrets.
+
+Generate
+--------
+
+Generates various secrets.
+
+MasterPassphrase
+^^^^^^^^^^^^^^^^
+
+Generates a secure master passphrase.
+
+Usage:
+
+::
+
+    airshipctl secret generate masterpassphrase

docs/source/index.rst

@@ -23,4 +23,5 @@ airshipctl Documentation
 
    developers
    plugins
-   testing-guidelines
+   testing-guidelines
+   cli/cli