docs: improved --help for pin remote commands

[lidel]

Part of #7559 and #7707 closes #7825

This PR adds docs in form of a longer description that is displayed when --help is passed on the CLI.
Those are pretty important, as CLI crowd often does not read docs online, and prefer to explore features this way.

While at it, unified some language to match fields in the config file and other places (thx @Gozala!) + included some tips and best practices which should improve onboarding experience.

@jessicaschilling this falls under our effort to improve onboarding: lmk if anything sounds awkward, or we could rephrase to make it even more intuitive.

cc @ipfs/wg-pinning-services

--help previews

Below are previews of the initial version of this PR:

Click to expand: ipfs pin remote service add --help

USAGE
  ipfs pin remote service add <service> <endpoint> <key> - Add remote pinning service.

SYNOPSIS
  ipfs pin remote service add [--] <service> <endpoint> <key>

ARGUMENTS

  <service>  - Service name.
  <endpoint> - Service endpoint.
  <key>      - Service key.

DESCRIPTION

  Add a credentials for access to a remote pinning service and store them in the
  config under Pinning.RemoteServices map.
  
  TIP:
  
    To add services and test them by fetching pin count stats:
  
    $ ipfs pin remote service add goodsrv https://pin-api.example.com secret-key
    $ ipfs pin remote service add badsrv  https://bad-api.example.com invalid-key
    $ ipfs pin remote service ls --stat
    goodsrv   https://pin-api.example.com 0/0/0/0
    badsrv    https://bad-api.example.com invalid

Click to expand: ipfs pin remote service ls --help

USAGE
  ipfs pin remote service ls - List remote pinning services.

SYNOPSIS
  ipfs pin remote service ls [--stat]

OPTIONS

  --stat  bool - Try to fetch and display current pin count on remote service (queued/pinning/pinned/failed). Default: false.

DESCRIPTION

  List remote pinning services.
  
  By default only a name and an endpoint are listed, however one can pass '--stat'
  to test each endpoint by fetching pin counts for each state:
  
    $ ipfs pin remote service ls --stat
    goodsrv   https://pin-api.example.com 0/0/0/0
    badsrv    https://bad-api.example.com invalid
  
  TIP: pass '--enc=json' for more useful JSON output.

Click to expand: ipfs pin remote add --help

USAGE
  ipfs pin remote add <ipfs-path-or-cid> - Pin object to remote pinning service.

SYNOPSIS
  ipfs pin remote add [--service=<service>] [--name=<name>] [--background] [--] <ipfs-path-or-cid>

ARGUMENTS

  <ipfs-path-or-cid> - Path to object(s) to be pinned.

OPTIONS

  --service     string - Name of the remote pinning service to use (mandatory).
  --name        string - An optional name for the pin.
  --background  bool   - Add to the queue on the remote service and return immediately (does not wait for pinned status). Default: false.

DESCRIPTION

  Asks remote pinning service to pin an IPFS object from a given path or a CID.
  
  To pin CID 'bafkqaaa' to service named 'mysrv' under a pin named 'mypin':
  
    $ ipfs pin remote add --service=mysrv --name=mypin bafkqaaa
  
  The above command will block until remote service returns 'pinned' status,
  which may take time depending on the size and available providers of the pinned
  data.
  
  If you prefer to not wait for pinning confirmation and return immediatelly
  after remote service confirms 'queued' status, add the '--background' flag:
  
    $ ipfs pin remote add --service=mysrv --name=mypin --background bafkqaaa
  
  Status of background pin requests can be inspected with the 'ls' command:
  
    $ ipfs pin remote ls --service=mysrv --cid=bafkqaaa --status=queued,pinning,pinned,failed

Click to expand: ipfs pin remote ls --help

USAGE
  ipfs pin remote ls - List objects pinned to remote pinning service.

SYNOPSIS
  ipfs pin remote ls [--service=<service>] [--name=<name>] [--cid=<cid>]... [--status=<status>]...

OPTIONS

  --service  string - Name of the remote pinning service to use (mandatory).
  --name     string - Return pins with names that contain provided value (case-sensitive, exact match).
  --cid      array  - Return pins for the specified CIDs (comma separated).
  --status   array  - Return pins with the specified statuses (queued,pinning,pinned,failed). Default: [pinned].

DESCRIPTION

  Returns a list of objects that are pinned to a remote pinning service.
  
  NOTE: by default it will only show matching objects in 'pinned' state.
  Pass '--status=queued,pinning,pinned,failed' to list pins in all states

Click to expand: ipfs pin remote rm --help

USAGE
  ipfs pin remote rm - Remove pins from remote pinning service.

SYNOPSIS
  ipfs pin remote rm [--service=<service>] [--name=<name>] [--cid=<cid>]... [--status=<status>]... [--force]

OPTIONS

  --service  string - Name of the remote pinning service to use (mandatory).
  --name     string - Remove pins with names that contain provided value (case-sensitive, exact match).
  --cid      array  - Remove pins for the specified CIDs.
  --status   array  - Remove pins with the specified statuses (queued,pinning,pinned,failed). Default: [pinned].
  --force    bool   - Allow removal of multiple pins matching the query without additional confirmation. Default: false.

DESCRIPTION

  Removes remote pins allowing them to be garbage collected if needed.
  
  This command accepts the same search query parameters as 'ls' and it is a good
  practice to execute 'ls' before 'rm' to confirm the list of pins to be removed.
  
  To remove a single pin for a specific CID:
  
    $ ipfs pin remote ls --service=mysrv --cid=bafkqaaa
    $ ipfs pin remote rm --service=mysrv --cid=bafkqaaa
  
  When more than one pin is matching the query on the remote service an error is
  returned.  To confirm removal of multiple pins pass '--force':
  
    $ ipfs pin remote ls --service=mysrv --name=popular-name
    $ ipfs pin remote rm --service=mysrv --name=popular-name --force
  
  NOTE: When no '--status' is passed, implicit '--status=pinned' is used.
  To list and then remove all pending pin requests pass an explicit status list:
  
    $ ipfs pin remote ls --service=mysrv --status=queued,pinning,failed
    $ ipfs pin remote rm --service=mysrv --status=queued,pinning,failed --force

[jessicaschilling]

Some small readability nits but looks great. Thank you!

[aschmahmann]

Thanks 😃, this is great. Appreciate the comments from @jessicaschilling. Let me know when you're ready to merge.

[lidel]

@aschmahmann applied improvements from @jessicaschilling, should be ready for merge 👍

[aschmahmann]

We support --status=queued --status=pinning ... via the StringsOption option.

We currently have some code that allow each --status=ABC that has commas in it to be flattened together, IMO this behavior is a little confusing and if we keep both then we should definitely document it.

@lidel why are we supporting the comma separated version is it for user ergonomics, compatibility with clients that refuse to send repeated HTTP query parameters or both?

If it's just for user ergonomics we may want to not tie ourselves to processing this server side and add this into the CLI processing for go-ipfs-cmds (e.g. https://github.com/ipfs/go-ipfs-cmds/blob/edc78ef36c1dadd4d1a87737e9a1727e59d36c45/cli/parse.go#L101).

[lidel]

@aschmahmann
It is just for user ergonomics. I was playing with CLI and the alternative is pretty tedious.
I am considering adding --status=any (https://github.com/ipfs/go-pinning-service-http-client/issues/7) to improve it even further.

My concern with adding it as a global feature of go-ipfs-cmds is that it will block use of , in values, it becomes a value separator. Here, its fine, as , won't be part of status or cid, but we don't know if its equally safe for other places: what if I want to pass multiple unix file paths, and one of them has , in file or dir name?

I suggest we keep it local to pin remote commands to unblock 0.8.0.
We can refactor and figure out how to handle it globally in future releases.

[aschmahmann]

What about if we allowed passing an option into StringsOption with a delimiter. If the delimiter is defined (e.g. a comma, colon, etc) the it would be used, but otherwise you'd have to pass multiple options instead of using a delimiter

[lidel]

Yeah, that would be 👌 – removes risk I described.

[aschmahmann]

Cool, I'll poke around go-ipfs-cmds and see how annoying this is to implement. Thinking it should be a little painful but not too bad.

Note: we'll need docs describing this behavior and that the delimiter exists and only applies to the CLI since the HTTP API docs are generated from these comments too 😬

[aschmahmann]

This has been implemented in go-ipfs-cmds and the dep bubbled into go-ipfs, this PR can be rebased on master to take advantage of it. #7863

[lidel]

@aschmahmann rebased and looks green, mind taking a final look?

[aschmahmann]

Looks great, thank you @lidel and @jessicaschilling. All our examples here use the comma delimited syntax without specific callouts that:

1. It is valid to do repeated option passing (i.e. ipfs pin remote ls --service=mysrv --status=queued --status=pinned
2. It is valid for the repeated options to be delimited (i.e. ipfs pin remote ls --service=mysrv --status=queued,pinned --status=pinning,failed)
3. The HTTP API doesn't work with any of this delimited business

We may want to do these in subsequent PRs (and perhaps just leave 3 to ipfs-inactive/http-api-docs#40).

For now I'm going to merge this though since it's much better than what we currently have.