Is there something like C#'s "see cref" in Python ReST docstrings?

Question

I'm converting some C# code to Python 3, including documentation which is typically written as XML summaries in the original C# code.

Those summaries have references to class names as a <see cref="ClassName"/> element or <paramref name="fileName"/> elements for references to parameters, creating clickable links when converting it to HTML for example. I wonder if there's something similar in the Python ReST docstring format I use.

For example, let's take this C# method documentation:

/// <summary>
/// Reads and returns a <see cref="DummyFile"/> instance from the file with the
/// given <paramref name="fileName"/>.
/// </summary>
/// <param name="fileName">The name of the file to read the data from.</param>
/// <returns>The read <see cref="DummyFile"/> instance.</returns>
public DummyFile LoadDummyFile(string fileName)
{
    // Do some dummy file work.
}

In Python, I'd convert this to:

"""
Reads and returns a DummyFile instance from the file with the given file_name.
:param file_name: The name of the file to read the data from.
:param str file_name: The name of the file to read the data from.
:return: The read DummyFile instance.
:rtype: DummyFile
"""
def load_dummy_file(file_name: str) -> DummyFile
    # Do some dummy file work.

(Does anyone even use :rtype?) As you can see, I simply entered the class name and parameter name as plain-text, not knowing if there is such special syntax to create clickable links out of it when creating web documentation later on.

Is it possible to create such class references in ReST docstrings, and if yes, what would be a possible (hopefully less lengthy than C#) syntax for them?

Answer 1

For <see cref="ClassName"> you could use

:py:class:`ClassName`

This will become a clickable ref to the class definition. See Sphinx Domains.

I don't know any similar methode for the file_name. But for what you need a clickable link to a place tow lines below?

I use this rtype directive.