Существует ли структурированный способ ссылки на метки параметров функций в строке документации Python?

Question

Я использую инструмент pydoc для автоматического создания документации. Учитывая функцию:

def sum(a, b):
  """Returns the sum of a and b."""
  return a + b

Мне интересно, если есть структурированный способ использовать уценку, чтобы выделить ссылки на метки параметров функции? Например:

"""Returns the sum of 'a' and 'b'."""
"""Returns the sum of `a` and `b."""
"""Returns the sum of *a* and *b*."""
"""Returns the sum of **a** and **b**."""

Аналогично этому вопросу. Ссылка на параметры в строке документации Python, которая предполагает использование Sphinx вместо pydoc.

Также обратите внимание, что мне любопытно ссылаться на метки (а не на типы) параметров функции.

Answer 1

В Pydoc нет поддержки уценки.

Форматирование в строках документации ограничено распознаванием ссылок PEP и RFC, self. ссылки на атрибуты и ссылки на существующие имена (для других классов, методов и функций) при рендеринге в HTML, поэтому в этом режиме некоторые имена уже будут размечены. Однако это не распространяется на имена аргументов.

Пидок действительно использует inspect.signature() вывод в качестве основы для форматирования функции, поэтому если вы убедитесь, что у вас есть информативные подсказки типов, то вы по крайней мере получите возможность документировать типы аргументов и возвращаемое значение.

Таким образом (довольно надуманное) определение с использованием общего TypeVar определение вместо того, чтобы придерживаться float, лайк:

from typing import TypeVar

Number = TypeVar('Number', int, float)

def sum(a: Number, b: Number) -> Number:
    """Produce the sum of the two numbers, a and b"""
    return a + b

выходит в pydoc как

sum(a: ~Number, b: ~Number) -> ~Number
    Produce the sum of the two numbers, a and b