docs: add a new page with global flags and link to it from the command docs

In f544234 we removed the global flags from each command as it was
making each page very big and causing 1000s of lines of duplication in
the man page.

This change adds a new flags page with all the global flags on and
links each command page to it.

Fixes #3273

cmd/gendocs/gendocs.go

@@ -1,7 +1,9 @@
 package gendocs
 
 import (
+	"bytes"
 	"fmt"
+	"io/ioutil"
 	"os"
 	"path"
 	"path/filepath"
@@ -35,12 +37,32 @@ supplied.  These are in a format suitable for hugo to render into the
 rclone.org website.`,
 	RunE: func(command *cobra.Command, args []string) error {
 		cmd.CheckArgs(1, 1, command, args)
-		out := args[0]
+		now := time.Now().Format(time.RFC3339)
+
+		// Create the directory structure
+		root := args[0]
+		out := filepath.Join(root, "commands")
 		err := os.MkdirAll(out, 0777)
 		if err != nil {
 			return err
 		}
-		now := time.Now().Format(time.RFC3339)
+
+		// Write the flags page
+		var buf bytes.Buffer
+		cmd.Root.SetOutput(&buf)
+		cmd.Root.SetArgs([]string{"help", "flags"})
+		cmd.GeneratingDocs = true
+		err = cmd.Root.Execute()
+		if err != nil {
+			return err
+		}
+		flagsHelp := strings.Replace(buf.String(), "YYYY-MM-DD", now, -1)
+		err = ioutil.WriteFile(filepath.Join(root, "flags.md"), []byte(flagsHelp), 0777)
+		if err != nil {
+			return err
+		}
+
+		// markup for the docs files
 		prepender := func(filename string) string {
 			name := filepath.Base(filename)
 			base := strings.TrimSuffix(name, path.Ext(name))
@@ -51,10 +73,42 @@ rclone.org website.`,
 			base := strings.TrimSuffix(name, path.Ext(name))
 			return "/commands/" + strings.ToLower(base) + "/"
 		}
+
 		// Hide all of the root entries flags
 		cmd.Root.Flags().VisitAll(func(flag *pflag.Flag) {
 			flag.Hidden = true
 		})
-		return doc.GenMarkdownTreeCustom(cmd.Root, out, prepender, linkHandler)
+		err = doc.GenMarkdownTreeCustom(cmd.Root, out, prepender, linkHandler)
+		if err != nil {
+			return err
+		}
+
+		// Munge the files to add a link to the global flags page
+		err = filepath.Walk(out, func(path string, info os.FileInfo, err error) error {
+			if err != nil {
+				return err
+			}
+			if !info.IsDir() {
+				b, err := ioutil.ReadFile(path)
+				if err != nil {
+					return err
+				}
+				doc := string(b)
+				doc = strings.Replace(doc, "\n### SEE ALSO", `
+See the [global flags page](/flags/) for global options not listed here.
+
+### SEE ALSO`, 1)
+				err = ioutil.WriteFile(path, []byte(doc), 0777)
+				if err != nil {
+					return err
+				}
+			}
+			return nil
+		})
+		if err != nil {
+			return err
+		}
+
+		return nil
 	},
 }