docs: standardize how we refer to methods in docstrings

[jku]

Current behavior:
Currently we use several different ways to refer to methods, objects and arguments in the Metadata API and ngclient docstrings. Examples:

:func:`~tuf.ngclient.updater.Updater.refresh()`    # creates a clickable link in RTD, is ugly in source
Updater.refresh()    # does not stand out from text in either RTD or source code
`Updater.refresh()`    # does not stand out from text in RTD
``Updater.refresh()``    # is rendered as "inline code" in RTD

This has been partially on purpose to see what these all look like (both in published docs and in code).

Expected behavior:

Ideally we should be consistent and follow the coding style guidelines (which somewhat reasonably argue against the sphinx links). The chosen method should be useful in the published docs and not ruin the docstring readability in source code. We'd want to apply the style in docstrings in tuf/api/ and tuf/ngclient/ (as those are used to produce the ReadTheDocs api docs).

After seeing all options I think I lean on using ``refresh()``: it creates a distinct rendering on ReadTheDocs and does not ruin the docstring readability in source code like the sphinx link format does. It does not create a clickable link but usually docstring text does not need that.

#1590 has many examples of using this format.

[lukpueh]

+1 for double back-ticks. Note to myself: Add a corresponding line to https://github.com/secure-systems-lab/code-style-guidelines/blob/master/python.md#docstrings.

[jku]

I didn't specify the argument names in function docstrings, which is probably the most common case... but maybe the same applies in that case: when argument names are used in the docstring, use double-backticks to get the code rendering?

[lukpueh]

I didn't specify the argument names in function docstrings...

Not sure I understand. Where did you not specify them? Above you do say "...ways to refer to methods, objects and arguments...".

At any rate, I think it's fine to use double-backticks for all of these, unless it turns out they clutter the docstrings in code or when rendered on RTD.

[jku]

oops, so I did :) carry on then

[lukpueh]

@ivanayov made an effort to consolidate how we refer to methods etc. in this project (see #1856 and #1815 - thanks!). I'd say the this is now captured by the implicit code style "be consistent" and does not require an explicit recommendation in the style guide. Closing...