More useful client docstrings and CLI help messages

[Purposefully broad - hopefully this issue will spawn little child issues]

Much of the client and cli documentation gives a general idea of what something does but very little information about what that means or does - You can know how to call something but not what to do with it. In the words of the person who brought this concern to me: "You get about as much information as you would looking at the source code".

All descriptions can be improved by giving more information about the expected use-case or including lines like "used to x".

Critical examples include:

What is a lifetime model? Why would you want to add exceptions to it?

What's the difference between declaring something bad and quarantining a replica? Why would you ever do either?

Why would you add an identity instead of making a new account? What does the membership association get you?

An example of a docstring I think provides a lot of useful information:

list_rses(rse_expression:str) -> "Iterator[str, Any]"

    List RSEs matching an expression. 
    When no expression is given, all rse attributes will be returned. When supplied, only the name of the rse is returned. 

    :param rse_expression: Filtering RSE Expression. See https://rucio.cern.ch/documentation/started/concepts/rse_expressions for further details, defaults to None
    :return: Iterator with all matching RSEs, in dictionary form. 

    .. code-block:: python
        >> from rucio.client import Client
        >> c = Client()
        >> all_rses = [rse for rse in c.list_rses()]  # Do not filter the query to the server
        >> all_rses[0] # Returns all attributes of the query
        {'id': '123456789', 'rse': 'MOCK', 'country_name': 'United States', 'vo': 'def', 'rse_type': 'DISK', 'deterministic': True, ...}

        >> filtered_rses = [rse for rse in c.list_rses("rse_type=DISK")] # Filter the query 
        >> filtered_rses # Returns just the names of the RSE that match the expression
        [{'rse': 'DVDKOL-DISK'}, {'rse': 'WJ-XROOTD'}, {'rse': 'MIVFZO-DISK'}, {'rse': 'EHSKVP-DISK'}]

        >> c.get_rse("DVDKOL-DISK") # Get all the information for the listed rse. 
        {'deterministic': True, 'domain': ['lan', 'wan'], 'id': '9012345678', 'lfn2pfn_algorithm': 'hash', 'rse': 'DVDKOL-DISK', 'rse_type': 'DISK', ...}

    Alo see: 
    :func: `get_rse`
    :func: `list_rse_attributes`

rucio / documentation

More useful client docstrings and CLI help messages #363

list_rses(rse_expression:str) -> "Iterator[str, Any]"