Merge pull request #107 from doanac/mkdocs

Improve help text rendering

cmd/docs.go

@@ -8,15 +8,15 @@ import (
 	"github.com/spf13/cobra/doc"
 )
 
-var docsCmd = &cobra.Command{
+var docsRstCmd = &cobra.Command{
 	Use:    "gen-rst [<directory to save files>]",
 	Short:  "Generate RST docs for this tool",
 	Hidden: true,
 	Args:   cobra.MaximumNArgs(1),
-	Run:    doGenDocs,
+	Run:    doGenRstDocs,
 }
 
-func doGenDocs(cmd *cobra.Command, args []string) {
+func doGenRstDocs(cmd *cobra.Command, args []string) {
 	outDir := "./"
 	if len(args) == 1 {
 		outDir = args[0]
@@ -38,3 +38,26 @@ func doGenDocs(cmd *cobra.Command, args []string) {
 		os.Exit(1)
 	}
 }
+
+var docsMdCmd = &cobra.Command{
+	Use:    "gen-md [<directory to save files>]",
+	Short:  "Generate markdown docs for this tool",
+	Hidden: true,
+	Args:   cobra.MaximumNArgs(1),
+	Run:    doGenMdDocs,
+}
+
+func doGenMdDocs(cmd *cobra.Command, args []string) {
+	outDir := "./"
+	if len(args) == 1 {
+		outDir = args[0]
+	}
+	fmt.Println("Generating docs at:", outDir)
+
+	rootCmd.DisableAutoGenTag = true
+	err := doc.GenMarkdownTree(rootCmd, outDir)
+	if err != nil {
+		fmt.Println("ERROR:", err)
+		os.Exit(1)
+	}
+}

cmd/root.go

@@ -59,7 +59,8 @@ func init() {
 	rootCmd.AddCommand(waves.NewCommand())
 	rootCmd.AddCommand(subcommands.GetCommand)
 
-	rootCmd.AddCommand(docsCmd)
+	rootCmd.AddCommand(docsRstCmd)
+	rootCmd.AddCommand(docsMdCmd)
 }
 
 func getConfigDir() string {

subcommands/config/set.go

@@ -15,16 +15,15 @@ func init() {
 		Short: "Create a new factory-wide configuration",
 		Long: `Creates a factory wide configuration. The fioconfig daemon running on
 each device will then be able to grab the latest version of the configuration
-and the device's configuration and apply it.
-
-Basic use can be done with command line arguments. eg:
-
+and the device's configuration and apply it. Use the --group parameter to 
+create a device group wide configuration instead.`,
+		Example: `
+  # Basic use
   fioctl config set npmtok="root" githubtok="1234"
 
-The configuration format also allows specifying what command to
-run after a configuration file is updated on the device. To take
-advantage of this, the "--raw" flag must be used. eg::
-
+  # The configuration format also allows specifying what command to
+  # run after a configuration file is updated on the device. To take
+  # advantage of this, the "--raw" flag must be used.
   cat >tmp.json <<EOF
   {
     "reason": "I want to use the on-changed attribute",
@@ -48,12 +47,9 @@ advantage of this, the "--raw" flag must be used. eg::
   > EOF
   fioctl config set --raw ./tmp.json
 
-fioctl will read in tmp.json and upload it to the OTA server.
-Instead of using ./tmp.json, the command can take a "-" and will read the
-content from STDIN instead of a file.
-
-Use a -g or --group parameter to create a device group wide configuration instead.
-`,
+  # fioctl will read in tmp.json and upload it to the OTA server.
+  # Instead of using ./tmp.json, the command can take a "-" and will read the
+  # content from STDIN instead of a file.`,
 		Run:  doConfigSet,
 		Args: cobra.MinimumNArgs(1),
 	}

subcommands/config/updates.go

@@ -16,10 +16,10 @@ func init() {
 		Run:   doConfigUpdates,
 		Long: `View or change factory wide configuration parameters used by aktualizr-lite for updating devices.
 When run with no options, this command will print out how the factory is
-currently configured. Configuration can be updated with commands
-like:
-
-  # Make devices start taking updates from Targets tagged with "devel"
+currently configured. Use the --group parameter to view or change a device 
+group wide configuration instead.`,
+		Example: `
+  # Make devices start taking updates from Targets tagged with "devel":
   fioctl config updates --tags devel
 
   # Make devices start taking updates from 2 different tags:
@@ -32,10 +32,7 @@ like:
   fioctl config updates --apps shellhttpd --tags master
 
   # Migrate devices from old docker-apps to compose-apps:
-  fioctl config updates --compose-apps
-
-Use a -g or --group parameter to view or change a device group wide configuration instead.
-`,
+  fioctl config updates --compose-apps`,
 	}
 	cmd.AddCommand(configUpdatesCmd)
 	configUpdatesCmd.Flags().StringP("group", "g", "", "Device group to use")

subcommands/devices/config_set.go

@@ -23,16 +23,14 @@ func init() {
 		Long: `Creates a secure configuration for device encrypting the contents each
 file using the device's public key. The fioconfig daemon running
 on each device will then be able to grab the latest version of the
-device's configuration and apply it.
-
-Basic use can be done with command line arguments. eg:
-
+device's configuration and apply it.`,
+		Example: `  
+  # Basic use can be done with command line arguments:
   fioctl device config set my-device npmtok="root"  githubtok="1234"
 
-The device configuration format also allows specifying what command
-to run after a configuration file is updated on the device. To take
-advantage of this, the "--raw" flag must be used. eg::
-
+  # The device configuration format also allows specifying what command
+  # to run after a configuration file is updated on the device. To take
+  # advantage of this, the "--raw" flag must be used.
   cat >tmp.json <<EOF
   {
     "reason": "I want to use the on-changed attribute",
@@ -56,9 +54,9 @@ advantage of this, the "--raw" flag must be used. eg::
   > EOF
   fioctl devices config set my-device --raw ./tmp.json
 
-fioctl will read in tmp.json, encrypt its contents, and upload it
-to the OTA server. Instead of using ./tmp.json, the command can take
-a "-" and will read the content from STDIN instead of a file.
+  # fioctl will read in tmp.json, encrypt its contents, and upload it
+  # to the OTA server. Instead of using ./tmp.json, the command can take
+  # a "-" and will read the content from STDIN instead of a file.
 `,
 		Run:  doConfigSet,
 		Args: cobra.MinimumNArgs(2),

subcommands/devices/config_updates.go

@@ -16,9 +16,8 @@ func init() {
 		Args:  cobra.ExactArgs(1),
 		Long: `View or change configuration parameters used by aktualizr-lite for updating a device.
 When run with no options, this command will print out how the device is
-currently configured and reporting. Configuration can be updated with commands
-like:
-
+currently configured and reporting.`,
+		Example: `
   # Make a device start taking updates from Targets tagged with "devel"
   fioctl devices config updates <device> --tags devel
 

subcommands/devices/list.go

@@ -107,7 +107,7 @@ func init() {
 		Short: "List devices registered to factories. Optionally include filepath style patterns to limit to device names. eg device-*",
 		Run:   doList,
 		Args:  cobra.MaximumNArgs(1),
-		Long:  "Available columns for display:\n  * " + strings.Join(allCols, "\n  * "),
+		Long:  "Available columns for display:\n\n  * " + strings.Join(allCols, "\n  * "),
 	}
 	cmd.AddCommand(listCmd)
 	listCmd.Flags().BoolVarP(&deviceNoShared, "just-mine", "", false, "Only include devices owned by you")

subcommands/keys/ca_create.go

@@ -30,7 +30,7 @@ func init() {
 		Long: `Perform a one-time operation to set up PKI infrastructure for managing
 the device gateway. This command creates a few things:
 
-# Root of trust for your factory: factory_ca.key / factory_ca.pem
+### Root of trust for your factory: factory_ca.key / factory_ca.pem
 The factory_ca keypair is generated by this command to define the PKI root of
 trust for this factory.
 
@@ -39,14 +39,14 @@ trust for this factory.
    Foundries.io. Once set, all future PKI related changes will require proof
    you own this certificate.
 
-# online-ca - A Foundries.io owned keypair to support lmp-device-register
+### online-ca - A Foundries.io owned keypair to support lmp-device-register
 In order for lmp-device-register to work, Foundries.io needs the ability to
 sign client certificates for devices. If enabled, the factory_ca keypair will
 sign the certificate signing request returned from the API.
 
 This is optional.
 
-# local-ca - A keypair you own
+### local-ca - A keypair you own
 This keypair can be used for things like your manufacturing process where you
 may set up devices without having to communicate with Foundries.io web
 services. This keypair is capable of signing client certificates for devices.

subcommands/secrets/update.go

@@ -17,9 +17,11 @@ func init() {
 	cmd.AddCommand(&cobra.Command{
 		Use:   "update secret_name=secret_val...",
 		Short: "Update secret(s) in a factory",
-		Long: `Update secrets in a factory.
-Secrets can be deleted by setting them to an empty value. eg:
+		Example: `
+  # Create or update a secret
+  fioctl secrets set githubtok=foo
 
+  # Delete a secret by setting it to an empty value. eg:
   fioctl secrets update secret_name=`,
 		Run:  doUpdate,
 		Args: cobra.MinimumNArgs(1),

subcommands/targets/deltas.go

@@ -27,17 +27,16 @@ func init() {
 can be downloaded significantly faster by generating OSTree static
 deltas. Static deltas are generated with a "from(sha) -> to(sha)" type
 logic. This command takes the given Target version and will produce a
-number of static deltas to ensure devices will be updated efficiently.
+number of static deltas to ensure devices will be updated efficiently.`,
+		Example: `
+  # There are two ways to run this command:
 
-There are two ways to run this command:
+  # Generate static deltas for 30->42 and 31->42
+  fioctl targets static-deltas 42 30 31
 
- # Generate static deltas for 30->42 and 31->42
- fioctl targets static-deltas 42 30 31
-
- # Find the target versions of all devices configured to the "prod" tag.
- # Generate a static delta from those versions to version 42.
- fioctl targets static-deltas --by-tag prod 42
-`,
+  # Find the target versions of all devices configured to the "prod" tag.
+  # Generate a static delta from those versions to version 42.
+  fioctl targets static-deltas --by-tag prod 42`,
 	}
 	cmd.AddCommand(deltas)
 	deltas.Flags().StringVarP(&byTag, "by-tag", "", "", "Find from-versions devices on the given tag")

subcommands/targets/tag.go

@@ -21,8 +21,14 @@ func init() {
 	var tagCmd = &cobra.Command{
 		Use:   "tag <target> [<target>...]",
 		Short: "Apply a comma separated list of tags to one or more targets.",
-		Run:   doTag,
-		Args:  cobra.MinimumNArgs(1),
+		Example: `
+  # Promote Target #42 currently tagged as master
+  fioctl targets tag --tags master,promoted --by-version 42
+
+  # Tag a specific Target by name
+  fioctl targets tag --tags master,testing intel-corei7-64-lmp-42`,
+		Run:  doTag,
+		Args: cobra.MinimumNArgs(1),
 	}
 	cmd.AddCommand(tagCmd)
 	tagCmd.Flags().StringVarP(&tagTags, "tags", "T", "", "comma,separate,list")