使用Sphinx与numpydoc规范文档化Python property的输入输出类型

核心规范 #

按照numpydoc的官方约定，property的所有文档统一写在getter方法上，不需要为setter单独编写docstring。如果给setter添加docstring，部分版本的Sphinx+numpydoc组合会出现文档读取冲突，导致最终生成的文档展示异常。

字段编写要求 #

你描述的读写属性需要在getter的docstring中同时覆盖赋值、取值的逻辑说明，需要包含以下字段：

• 开头简述属性的核心用途
• Parameters字段：说明赋值时支持的输入类型、逻辑处理规则，对应setter的入参要求
• Returns字段：说明取值时的返回类型、返回规则，对应getter的返回逻辑
• 如有特殊边界处理逻辑，可增加Notes字段补充说明

完整示例 #

修改后的代码参考如下：

from typing import Union
import numpy as np

class MyClass:
    def __init__(self):
        self._x = None
        
    @property
    def x(self) -> Union[float, np.ndarray]:
        """存储数值或数值数组的属性。

        Parameters
        ----------
        value : float, list, np.ndarray
            赋值时的输入值，支持单浮点数、数值列表、numpy数组三种类型，输入会自动转换为至少1维的numpy数组存储。
        
        Returns
        -------
        float or np.ndarray
            取值时，若存储的数组长度为1，返回单个浮点数；否则直接返回完整的numpy数组。
        
        Notes
        -----
        赋值时的维度转换依赖`np.atleast_1d`实现，内部始终以至少1维的数组格式存储数据，无标量存储场景。
        """
        if len(self._x) == 1:
            return self._x[0]
        else:
            return self._x
    
    @x.setter
    def x(self, value: Union[float, list, np.ndarray]):
        self._x = np.atleast_1d(value)

上述写法生成的文档会完整展示属性的读写规则，和numpy官方库的同类属性文档格式完全一致。

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