python - 是否有结构化的方式来引用 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