如何通过Sphinx Autodoc从变量提取参数可选值至文档字符串？

当然可以这么做，而且这确实是避免文档和代码脱节的好办法。下面给你几种实用的实现方式：

方法1：定义函数后手动格式化文档字符串 #

这种方式简单直接，适合单个函数的场景：

authorized_values = [1, 2, 3]

def foo(a: int):
    """Print an integer between 1 and 3.

    Args:
        a: The integer to print. The authorized values are: {authorized_values}.
    """
    if a not in authorized_values:  # 注意你示例里这里拼写错误，是authorized_values不是authorized_value
        raise ValueError(f"The authorized values are: {authorized_values}.")
    print(a)

# 格式化文档字符串，替换占位符
foo.__doc__ = foo.__doc__.format(authorized_values=authorized_values)

修改authorized_values后，重新运行这段代码就能同步更新文档内容。

方法2：用装饰器批量处理 #

如果有多个函数需要做这类操作，写个装饰器会更高效：

authorized_values = [1, 2, 3]

def inject_authorized_values(doc_placeholder="authorized_values"):
    def decorator(func):
        func.__doc__ = func.__doc__.format(**{doc_placeholder: authorized_values})
        return func
    return decorator

@inject_authorized_values()
def foo(a: int):
    """Print an integer between 1 and 3.

    Args:
        a: The integer to print. The authorized values are: {authorized_values}.
    """
    if a not in authorized_values:
        raise ValueError(f"The authorized values are: {authorized_values}.")
    print(a)

装饰器会自动替换文档里的占位符，后续修改authorized_values后，重新装饰函数即可更新文档。

方法3：直接使用f-string文档字符串（注意局限性） #

Python 3.6及以上支持f-string作为文档字符串，但要注意：这种方式是在函数定义时就解析了列表的值，后续修改authorized_values不会自动同步文档，除非重新定义函数。示例：

authorized_values = [1, 2, 3]

def foo(a: int):
    f"""Print an integer between 1 and 3.

    Args:
        a: The integer to print. The authorized values are: {authorized_values}.
    """
    if a not in authorized_values:
        raise ValueError(f"The authorized values are: {authorized_values}.")
    print(a)

如果不需要动态更新列表，或者每次修改列表后都会重新加载函数，这种方式最简洁。

最后提醒：不管用哪种方法，都要确保文档里的占位符和变量名一致，避免拼写错误影响代码运行。

内容的提问来源于stack exchange，提问作者StormRider