Merge pull request #33 from safesoftware/doc-generation

Add doc generation and docs.

README.md

@@ -28,12 +28,11 @@ fmeserver login https://my-fmeserver.com --token my-token-here
 fmeserver info
 ```
 
+For full documentation of all commands, see the [Documentation](doc/fmeserver.md).
+
+
 ## Development
 
-* `cobra-cli` will be needed to add new commands
-```
-go install github.com/spf13/cobra-cli@latest
-```
 * Run while coding:
 ```
 go run main.go
@@ -42,11 +41,6 @@ go run main.go
 ```
 go build -o fmeserver
 ```
-* Add a new command
-```
-cobra-cli add new-command
-```
-More details [here](https://github.com/spf13/cobra-cli/blob/main/README.md)
 
 A great resource for adding new structs to represent JSON returned from FME Server is this [JSON to Go converter](https://mholt.github.io/json-to-go/) which will create a Go struct for you from a JSON sample.
 
@@ -56,4 +50,4 @@ There is a github action that will run when a new release is created that will b
 
 ## Acknowledgments
 
-* Created using [cobra](https://github.com/spf13/cobra)
+* Created using [cobra](https://github.com/spf13/cobra)

cmd/jobs.go

@@ -67,7 +67,7 @@ func newJobsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "jobs",
 		Short: "Lists jobs on FME Server",
-		Long:  "Lists jobs on FME Server",
+		Long:  "Lists running, queued, and/or queued jobs on FME Server. Pass in a job id to get information on a specific job.",
 
 		Example: `
   # List all jobs (currently limited to the most recent 1000)

cmd/migrationTasks.go

@@ -57,8 +57,8 @@ func newMigrationTasksCmd() *cobra.Command {
 	f := migrationTasksFlags{}
 	cmd := &cobra.Command{
 		Use:   "tasks",
-		Short: "Retrieves the records for all migration tasks.",
-		Long:  "Retrieves the records for all migration tasks.",
+		Short: "Retrieves the records for migration tasks.",
+		Long:  "Retrieves the records for migration tasks. Get all migration tasks or for a specific task by passing in the id.",
 		Example: `
   # Get all migration tasks
   fmeserver migration tasks

cmd/projects.go

@@ -99,8 +99,8 @@ func newProjectsCmd() *cobra.Command {
 	f := projectsFlags{}
 	cmd := &cobra.Command{
 		Use:   "projects",
-		Short: "Lists all projects on the FME Server",
-		Long:  "Lists all projects on the FME Server",
+		Short: "Lists projects on the FME Server",
+		Long:  "Lists projects on the FME Server. Pass in a name to retrieve information on a single project.",
 		Example: `
   # List all projects
   fmeserver projects

cmd/projects_download.go

@@ -26,7 +26,7 @@ func newProjectDownloadCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "download",
 		Short: "Downloads an FME Server Project",
-		Long:  "Backs up the FME Server configuration to a local file or to a shared resource location on the FME Server.",
+		Long:  "Downloads an FME Server Project to a local file. Useful for backing up or moving a project to another FME Server.",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 
 			return nil

cmd/projects_upload.go

@@ -28,8 +28,8 @@ func newProjectUploadCmd() *cobra.Command {
 	f := projectUploadFlags{}
 	cmd := &cobra.Command{
 		Use:   "upload",
-		Short: "Imports FME Server Projects from a downloaded import package.",
-		Long:  "Imports FME Server Projects from a downloaded import package.",
+		Short: "Imports FME Server Projects from a downloaded package.",
+		Long:  "Imports FME Server Projects from a downloaded package. Useful for moving a project from one FME Server to another.",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			// verify import mode is valid
 			if f.importMode != "UPDATE" && f.importMode != "INSERT" {

cmd/refreshStatus.go

@@ -20,7 +20,7 @@ func newRefreshStatusCmd() *cobra.Command {
 	f := licenseRefreshStatusFlags{}
 	cmd := &cobra.Command{
 		Use:   "status",
-		Short: "Check status of license refresh",
+		Short: "Check the status of a license refresh request.",
 		Long:  "Check the status of a license refresh request.",
 		Example: `
 	# Output the license refresh status as a table

cmd/repositories.go

@@ -64,7 +64,7 @@ func newRepositoryCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "repositories",
 		Short: "List repositories",
-		Long:  `Lists repositories on the given FME Server.`,
+		Long:  `Lists repositories on the given FME Server. Pass in a name to get information on a specific repository.`,
 		Example: `
 	Examples:
 	# List all repositories

cmd/repositories_create.go

@@ -29,7 +29,7 @@ func newRepositoryCreateCmd() *cobra.Command {
 	f := repositoryCreateFlags{}
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Create a repository",
+		Short: "Create a new repository.",
 		Long:  `Create a new repository.`,
 		Example: `
 	Examples:

cmd/repositories_delete.go

@@ -22,7 +22,7 @@ func newRepositoryDeleteCmd() *cobra.Command {
 	f := repositoryDeleteFlags{}
 	cmd := &cobra.Command{
 		Use:   "delete",
-		Short: "Delete a repository",
+		Short: "Delete a repository.",
 		Long:  `Delete a repository.`,
 		Example: `
 	Examples:

cmd/requestStatus.go

@@ -20,7 +20,7 @@ func newLicenseRequestStatusCmd() *cobra.Command {
 	f := licenseRequestStatusFlags{}
 	cmd := &cobra.Command{
 		Use:   "status",
-		Short: "Check status of license request",
+		Short: "Check the status of a license request.",
 		Long:  "Check the status of a license request.",
 		Example: `
 	# Output the license request status as a table

cmd/root.go

@@ -28,12 +28,13 @@ var rootCmd = NewRootCommand()
 
 func NewRootCommand() *cobra.Command {
 	cmds := &cobra.Command{
-		Use:           "fmeserver",
-		Short:         "A command line interface for interacting with FME Server.",
-		Long:          `A command line interface for interacting with FME Server.`,
-		Version:       appVersion,
-		SilenceErrors: true,
-		SilenceUsage:  true,
+		Use:               "fmeserver",
+		Short:             "A command line interface for interacting with FME Server.",
+		Long:              `A command line interface for interacting with FME Server. See available commands below. Get started with the login command.`,
+		Version:           appVersion,
+		SilenceErrors:     true,
+		SilenceUsage:      true,
+		DisableAutoGenTag: true,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			// make sure the config file is set up correctly
 			_, err := os.Stat(viper.ConfigFileUsed())

cmd/run.go

@@ -94,8 +94,8 @@ func newRunCmd() *cobra.Command {
 	f := runFlags{}
 	cmd := &cobra.Command{
 		Use:   "run",
-		Short: "Run a workspace on FME Server",
-		Long: `Run a workspace on FME Server
+		Short: "Run a workspace on FME Server.",
+		Long: `Run a workspace on FME Server.
 		
 	Examples:
 	# Submit a job asynchronously

cmd/workspaces.go

@@ -335,10 +335,13 @@ func newWorkspaceCmd() *cobra.Command {
 	f := workspaceFlags{}
 	cmd := &cobra.Command{
 		Use:   "workspaces",
-		Short: "List workspaces by repository",
-		Long:  `Lists workspaces on the given FME Server in the repository.`,
+		Short: "List workspaces.",
+		Long:  `Lists workspaces that exist on the FME Server. Filter by repository, specify a name to retrieve a specific workspace, or specify a filter string to narrow down by name or title.`,
 		Example: `
 	Examples:
+	# List all workspaces on the FME Server
+	fmeserver workspaces
+	
 	# List all workspaces in Samples repository
 	fmeserver workspaces --repository Samples
 	
@@ -383,7 +386,7 @@ func newWorkspaceCmd() *cobra.Command {
 
 	cmd.Flags().StringVar(&f.repository, "repository", "", "Name of repository to list workspaces in.")
 	cmd.Flags().StringVar(&f.name, "name", "", "If specified, get details about a specific workspace")
-	cmd.Flags().StringVar(&f.filterString, "filter-string", "", "Specify the output type. Should be one of table, json, or custom-columns. Only usable with V4 API.")
+	cmd.Flags().StringVar(&f.filterString, "filter-string", "", "If specified, only workspaces with a matching name or title will be returned. Only usable with V4 API.")
 	cmd.Flags().StringVarP(&f.outputType, "output", "o", "table", "Specify the output type. Should be one of table, json, or custom-columns")
 	cmd.Flags().BoolVar(&f.noHeaders, "no-headers", false, "Don't print column headers")
 	cmd.Flags().Var(&f.apiVersion, "api-version", "The api version to use when contacting FME Server. Must be one of v3 or v4")

docgen/README.md

@@ -0,0 +1,14 @@
+# FME Server CLI Docgen
+
+This will generate docs based on the information for each command.
+
+## Generating the doc
+
+Run the command:
+```
+go run docgen.go
+```
+
+to regenerate the documentation in the `docs` directory.
+
+Before committing changes, use a diff tool to ensure changes are correct and any manual edits that have been made post-generation are restored.

docgen/docgen.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"log"
+
+	"github.com/safesoftare/fmeserver-cli/cmd"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	err := doc.GenMarkdownTree(cmd.NewRootCommand(), "../docs")
+	if err != nil {
+		log.Fatal(err)
+	}
+}