Я конвертирую некоторый код C# в Python 3, включая документацию, которая обычно записывается в виде сводок XML в исходном коде C#.
В этих сводках есть ссылки на имена классов в виде элемента <see cref="ClassName"/> или элементов <paramref name="fileName"/> для ссылок на параметры, создавая интерактивные ссылки, например, при преобразовании их в HTML. Интересно, есть ли что-то подобное в формате строки документации Python ReST, который я использую.
Например, возьмем эту документацию по методу C#:
/// <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.
}
В Python я бы преобразовал это в:
"""
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.
(Кто-нибудь вообще использует :rtype?) Как видите, я просто ввел имя класса и имя параметра в виде обычного текста, не зная, есть ли такой специальный синтаксис для создания из него кликабельных ссылок при создании веб-документации позже.
Можно ли создавать такие ссылки на классы в строках документации ReST, и если да, то какой для них будет возможный (надеюсь, менее длинный, чем C#) синтаксис?
