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
This commit is contained in:
Nick Craig-Wood 2018-04-23 20:44:44 +01:00
parent 21a10e58c9
commit 9ab2521ef2
7 changed files with 90 additions and 35 deletions

View File

@ -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

View File

@ -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
`,
})

21
bin/make_rc_docs.sh Executable file
View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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
}