如何在使用Sphinx编写的Python文档字符串中指示有效的范围？

Question

有没有一种方法可以使用Sphinx在Python文档字符串中指示“有效范围”？例如，请考虑以下线性函数。

def f(m, x, b):
    """
    Returns the `y` value of a linear function using slope-intercept form.
    
    :param x: The x-axis value.
    :type x: float
    :param m: The slope of the linear function.
    :type m: float
    :param b: The y-intercept.
    :type b: float
    """
    if x < 0:
        raise ValueError('The min "x" value of this function is 0')
    return m * x + b

有没有一种方法可以指示变量 x 的域为“x必须大于零”？或者用区间表示法，[0, infinity]。

具体而言，有没有一种方法可以使用Sphinx在Python docstring中记录这一点？

- MikeyE

---

为什么不直接将其附加到定义中呢？:param x: x轴的值。该函数的最小“x”值为0。 - Steve Piercy

@StevePiercy 我可以这样做，但我希望Sphinx中有一个选项（或其他东西）可以添加一些特殊格式到函数的“domain”，这样在渲染后查看文档时更容易注意到。 - MikeyE

没有这种功能。Autodoc只解析Python域中方法的签名和文档字符串，而不是任意代码。 - Steve Piercy

用符合Python风格的方式定义一个domain的方法是在docstring中定义一个doctest，然后Sphinx会根据所选的主题渲染它为一个警告。需要注意的是，doctest是一个简单的Python构造，主要用于表达简单的情况。对于更复杂的用例，您可以实现一个domain类，对其进行文档记录，并进行交叉引用。文档一致性的关键在于，您可以使用反引号或粗体等形式进行语言上的说明来表达domain是什么。 - bad_coder

您可能还想考虑一下从基本的ReST语法切换的优势。 - bad_coder

Answer 1

默认情况下，Python模块采用UTF-8编码，因此字符将正常显示。字符串字面值可以使用Unicode字符或在docstring中使用u前缀写入相应的十六进制代码。这使得数学Unicode范围可以在docstring中写入。

Python将程序文本作为Unicode代码点读取；源文件的编码可以通过编码声明给出，并默认为UTF-8，请参见PEP 3120了解详情。

使用Google样式docstring编写的显式和带有u前缀的Unicode字符示例字符串字面值：

def f(m, x, b) -> float:
    """
    Returns the `y` value of a linear function using slope-intercept form.

    Args:
        x (float): The x-axis value.
        m (float): The slope of the linear function.
        b (float): The y-intercept.
    Returns:
        float: The y-axis value.
    Raises:
        ValueError: Value of `x` ∈ [0, ∞], or `x` \u2208\u005B 0, \u221E\u005D.

    """
    if x < 0:
        raise ValueError('The min "x" value of this function is 0')
    return m * x + b

结果：

这对于简单的方程式来说效果很好，如果你想写更复杂的数学表达式Sphinx有几个扩展可以将它们输出为HTML。

- bad_coder