From 9ab2521ef2ec00fcf74fd85834609b740652b752 Mon Sep 17 00:00:00 2001
From: Nick Craig-Wood <nick@craig-wood.com>
Date: Mon, 23 Apr 2018 20:44:44 +0100
Subject: [PATCH] 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 | 3 ++
backend/cache/cache.go | 5 +++
bin/make_rc_docs.sh | 21 ++++++++++
docs/content/rc.md | 76 ++++++++++++++++++++++-------------
fs/accounting/token_bucket.go | 4 +-
fs/rc/internal.go | 4 +-
fs/rc/registry.go | 12 ++++--
7 files changed, 90 insertions(+), 35 deletions(-)
create mode 100755 bin/make_rc_docs.sh
diff --git a/Makefile b/Makefile
index f262bdce3..c2de58243 100644
--- a/Makefile
+++ b/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
diff --git a/backend/cache/cache.go b/backend/cache/cache.go
index 6abed89a9..a78f64e31 100644
--- a/backend/cache/cache.go
+++ b/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
`,
})
diff --git a/bin/make_rc_docs.sh b/bin/make_rc_docs.sh
new file mode 100755
index 000000000..1f2c3e113
--- /dev/null
+++ b/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
diff --git a/docs/content/rc.md b/docs/content/rc.md
index f85a73b2b..8502d007d 100644
--- a/docs/content/rc.md
+++ b/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.
-Params:
+### core/memstats: Returns the memory statistics
- - remote = path to remote (required)
- - withData = true/false to delete cached data (chunks) as well (optional)
+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
-Eg
+The most interesting values for most people are:
- rclone rc cache/expire remote=path/to/sub/folder/
- rclone rc cache/expire remote=/ withData=true
+* HeapAlloc: This is the amount of memory rclone is actually using
+* 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
-
-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.
+<!--- autogenerated stop -->
## Accessing the remote control via HTTP
diff --git a/fs/accounting/token_bucket.go b/fs/accounting/token_bucket.go
index 9990d3d93..60005dcc0 100644
--- a/fs/accounting/token_bucket.go
+++ b/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 core/bwlimit rate=off
+ rclone rc core/bwlimit rate=1M
+ 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.
diff --git a/fs/rc/internal.go b/fs/rc/internal.go
index 70a579c8e..307d852e1 100644
--- a/fs/rc/internal.go
+++ b/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
diff --git a/fs/rc/registry.go b/fs/rc/registry.go
index 9287805bd..54a4dc953 100644
--- a/fs/rc/registry.go
+++ b/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 {
- out = append(out, call)
+ var keys []string
+ for key := range r.call {
+ keys = append(keys, key)
+ }
+ sort.Strings(keys)
+ for _, key := range keys {
+ out = append(out, r.call[key])
}
return out
}