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中不支持降价。

文档字符串中的格式限制为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，则至少将要记录参数的类型和返回值。

因此，使用通用的public class UserViewModel extends AndroidViewModel { private AppRepository mRepository; public UserViewModel(Application application) { super(application); mRepository=new AppRepository(application); } public LiveData<User> getUser(String username) { return mRepository.getUser(username); } }定义而不是坚持使用TypeVar来定义（而是人为的）定义，例如：

float

在pydoc中显示为

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

有没有一种结构化的方法来引用Python docstring中的函数参数标签？

1 个答案: