docs: standardize how we refer to methods in docstrings

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.

https://github.com/theupdateframework/python-tuf/pull/1590 has many examples of using this format.

[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…