From 9ab2521ef2ec00fcf74fd85834609b740652b752 Mon Sep 17 00:00:00 2001 From: Nick Craig-Wood 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} + /^ +### 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. + ## 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 }