是否有结构化的方式来引用 Python 文档字符串中的函数参数标签？

Question

我正在使用工具pydoc 自动生成文档。给定函数：

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

我很好奇是否有一种结构化的方式来使用 Markdown 来突出对函数参数标签的引用？例如：

"""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**."""

类似于Referencing parameters in a Python docstring 这个问题，它是关于使用 Sphinx 而不是 pydoc。

另外请注意，我对引用函数参数的标签（而不是类型）感到好奇。

Answer 1

Pydoc 中不支持 markdown。

文档字符串中的格式仅限于recognising PEP and RFC references, self. attribute references and links for existing names (for other classes, methods, and functions) when rendering to HTML，因此在该模式下，一些名称已经被标记。但是，这不会扩展到参数名称。

Pydoc 确实使用inspect.signature() output 作为格式化函数的基础，所以如果你确定你有informative type hints，那么你至少可以记录参数的类型和返回值。

所以使用通用的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