rc: autogenerate and tidy the docs and commands

* Rename rc/pid -> core/pid
  * Sort the output of `rc list`
  * Make a script to autogenerate the docs
  * Tidy docs

Makefile

@@ -92,6 +92,9 @@ MANUAL.txt:	MANUAL.md
 commanddocs: rclone
 	rclone gendocs docs/content/commands/
 
+rcdocs: rclone
+	bin/make_rc_docs.sh
+
 install: rclone
 	install -d ${DESTDIR}/usr/bin
 	install -t ${DESTDIR}/usr/bin ${GOPATH}/bin/rclone

backend/cache/cache.go

@@ -429,6 +429,11 @@ Purge a remote from the cache backend. Supports either a directory or a file.
 Params:
   - remote = path to remote (required)
   - withData = true/false to delete cached data (chunks) as well (optional)
+
+Eg
+
+    rclone rc cache/expire remote=path/to/sub/folder/
+    rclone rc cache/expire remote=/ withData=true 
 `,
 	})
 

bin/make_rc_docs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Insert the rc docs into docs/content/rc.md
+
+set -e
+
+go install
+mkdir -p /tmp/rclone_cache_test
+export RCLONE_CONFIG_RCDOCS_TYPE=cache
+export RCLONE_CONFIG_RCDOCS_REMOTE=/tmp/rclone/cache_test
+rclone -q --rc mount rcdocs: /mnt/tmp/ &
+sleep 0.5
+rclone rc > /tmp/z.md
+fusermount -z -u /mnt/tmp/
+
+awk '
+    BEGIN       {p=1}
+    /^<!--- autogenerated start/  {print;system("cat /tmp/z.md");p=0}
+    /^<!--- autogenerated stop/   {p=1}
+    p' docs/content/rc.md > /tmp/rc.md
+
+mv /tmp/rc.md docs/content/rc.md

docs/content/rc.md

@@ -68,6 +68,22 @@ Run `rclone rc` on its own to see the help for the installed remote
 control commands.
 
 ## Supported commands
+<!--- autogenerated start - run make rcdocs - don't edit here -->
+### cache/expire: Purge a remote from cache
+
+Purge a remote from the cache backend. Supports either a directory or a file.
+Params:
+  - remote = path to remote (required)
+  - withData = true/false to delete cached data (chunks) as well (optional)
+
+Eg
+
+    rclone rc cache/expire remote=path/to/sub/folder/
+    rclone rc cache/expire remote=/ withData=true
+
+### cache/stats: Get cache stats
+
+Show statistics for the cache remote.
 
 ### core/bwlimit: Set the bandwidth limit.
 
@@ -78,18 +94,41 @@ Eg
     rclone rc core/bwlimit rate=1M
     rclone rc core/bwlimit rate=off
 
-### cache/expire: Purge a remote from cache
+The format of the parameter is exactly the same as passed to --bwlimit
+except only one bandwidth may be specified.
 
-Purge a remote from the cache backend. Supports either a directory or a file.
+### core/memstats: Returns the memory statistics
-Params:
 
-  - remote = path to remote (required)
+This returns the memory statistics of the running program.  What the values mean
-  - withData = true/false to delete cached data (chunks) as well (optional)
+are explained in the go docs: https://golang.org/pkg/runtime/#MemStats
 
-Eg
+The most interesting values for most people are:
 
-    rclone rc cache/expire remote=path/to/sub/folder/
+* HeapAlloc: This is the amount of memory rclone is actually using
-    rclone rc cache/expire remote=/ withData=true 
+* HeapSys: This is the amount of memory rclone has obtained from the OS
+* Sys: this is the total amount of memory requested from the OS
+  * It is virtual memory so may include unused memory
+
+### core/pid: Return PID of current process
+
+This returns PID of current process.
+Useful for stopping rclone process.
+
+### rc/error: This returns an error
+
+This returns an error with the input as part of its error string.
+Useful for testing error handling.
+
+### rc/list: List all the registered remote control commands
+
+This lists all the registered remote control commands as a JSON map in
+the commands response.
+
+### rc/noop: Echo the input to the output parameters
+
+This echoes the input parameters to the output parameters for testing
+purposes.  It can be used to check that rclone is still alive and to
+check that parameter passing is working properly.
 
 ### vfs/forget: Forget files or directories in the directory cache.
 
@@ -107,26 +146,7 @@ starting with dir will forget that dir, eg
 
     rclone rc vfs/forget file=hello file2=goodbye dir=home/junk
 
-### rc/noop: Echo the input to the output parameters
+<!--- autogenerated stop -->
-
-This echoes the input parameters to the output parameters for testing
-purposes.  It can be used to check that rclone is still alive and to
-check that parameter passing is working properly.
-
-### rc/error: This returns an error
-
-This returns an error with the input as part of its error string.
-Useful for testing error handling.
-
-### rc/pid: Return PID of current process
-
-This returns PID of current process.
-Useful for stopping rclone process.
-
-### rc/list: List all the registered remote control commands
-
-This lists all the registered remote control commands as a JSON map in
-the commands response.
 
 ## Accessing the remote control via HTTP
 

fs/accounting/token_bucket.go

@@ -149,8 +149,8 @@ This sets the bandwidth limit to that passed in.
 
 Eg
 
-    rclone core/bwlimit rate=1M
+    rclone rc core/bwlimit rate=1M
-    rclone core/bwlimit rate=off
+    rclone rc core/bwlimit rate=off
 
 The format of the parameter is exactly the same as passed to --bwlimit
 except only one bandwidth may be specified.

fs/rc/internal.go

@@ -36,7 +36,7 @@ This lists all the registered remote control commands as a JSON map in
 the commands response.`,
 	})
 	Add(Call{
-		Path:  "rc/pid",
+		Path:  "core/pid",
 		Fn:    rcPid,
 		Title: "Return PID of current process",
 		Help: `
@@ -46,7 +46,7 @@ Useful for stopping rclone process.`,
 	Add(Call{
 		Path:  "core/memstats",
 		Fn:    rcMemStats,
-		Title: "Returns the memory statistics of the running program",
+		Title: "Returns the memory statistics",
 		Help: `
 This returns the memory statistics of the running program.  What the values mean
 are explained in the go docs: https://golang.org/pkg/runtime/#MemStats

fs/rc/registry.go

@@ -3,6 +3,7 @@
 package rc
 
 import (
+	"sort"
 	"strings"
 	"sync"
 
@@ -54,12 +55,17 @@ func (r *Registry) get(path string) *Call {
 	return r.call[path]
 }
 
-// get a list of all calls
+// get a list of all calls in alphabetical order
 func (r *Registry) list() (out []*Call) {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
-	for _, call := range r.call {
+	var keys []string
-		out = append(out, call)
+	for key := range r.call {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		out = append(out, r.call[key])
 	}
 	return out
 }