Improving docstrings

[rdimaio]

Partly related to: rucio/documentation#287.

It seems like there is no single style for docstrings in Rucio, e.g.:

For the docstring blocks:

• Sometimes single quotes are used:

  rucio/lib/rucio/api/vo.py

  Line 32 in a7f97ed

  '''

• Mostly, double quotes are used:

  rucio/lib/rucio/api/rule.py

  Line 138 in a7f97ed

  """

For returns:

• In some places we use :return:, e.g.: https://github.com/rucio/rucio/blob/master/lib/rucio/common/didtype.py#L162
• In other places we use :returns:, e.g.: https://github.com/rucio/rucio/blob/master/lib/rucio/tests/common.py#L101

For exceptions:

• :raises: https://github.com/rucio/rucio/blob/master/lib/rucio/common/config.py#L337
• :raises:: https://github.com/rucio/rucio/blob/master/lib/rucio/api/rule.py#L224

I think we should agree on:

• What format we should use for docstrings
• Where do we want to add docstrings
• Whether to automatically generate documentation from docstrings

[voetberg]

Some automatic generation is already done for the API/Client - https://github.com/rucio/documentation/blob/main/tools/run_in_docker/generate_client_api_docs.sh , but I do agree

[rdimaio]

Reopening as that was only an initial PR, there is still some extra work to be done