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

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

0 голосов
/ 01 ноября 2018

Я использую инструмент 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.

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

1 Ответ

0 голосов
/ 01 ноября 2018

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

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

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

Итак, (довольно надуманное) определение, использующее общее определение 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
...