使用python-attrs时有没有好的方案为类属性添加文档说明？

以下三种方案都可以满足你的需求，文档都能在IPython/Jupyter中正常展示：

方案1：类docstring加参数描述（全版本兼容） #

Jupyter和IPython原生支持解析类docstring中的参数说明块，你直接在类的docstring里按照常用的文档风格（numpy风格、谷歌风格、reST风格都可）补充参数说明即可，不需要额外配置：

import attr

@attr.s
class Coordinates(object):
    """
    一组坐标数据
    
    Parameters
    ----------
    x : float
        横坐标，单位：角度
    y : float
        纵坐标，单位：角度
    """
    x = attr.ib()
    y = attr.ib()

执行Coordinates?查询时，类的docstring会完整展示，用户直接就能看到两个参数的含义和单位。

方案2：字段元数据自动生成init文档（适配attrs 20.1.0及以上版本） #

你可以给每个attr.ib()添加doc属性到元数据中，同时开启auto_doc开关，attrs会自动将字段说明合并到生成的__init__方法文档中：

import attr

@attr.s(auto_doc=True)
class Coordinates(object):
    """一组坐标数据"""
    x = attr.ib(metadata={"doc": "横坐标，单位：角度"})
    y = attr.ib(metadata={"doc": "纵坐标，单位：角度"})

这个方案的优势是字段定义和说明绑定，后期维护字段时不需要单独修改docstring，生成的init文档会自动罗列所有参数的说明。

方案3：自定义__init__保留原有书写习惯 #

如果你完全不想改变原来给__init__写docstring的习惯，可以关闭attrs自动生成init的开关，自己实现init方法，同时保留attrs其他所有能力：

import attr

@attr.s(init=False)
class Coordinates(object):
    """一组坐标数据"""
    x = attr.ib()
    y = attr.ib()
    
    def __init__(self, x: float, y: float):
        """
        创建坐标实例
        
        :param x: 横坐标，单位：角度
        :param y: 纵坐标，单位：角度
        """
        self.x = x
        self.y = y

这个方案的文档展示效果和普通手写类完全一致，你还可以正常使用attrs的验证器、转换器、序列化等所有功能。

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