什么是Sphinx注释？

一、什么是Sphinx注释？ Sphinx注释是Python文档字符串(docstring)的一种标准格式，主要用于：

生成专业级API文档（通过Sphinx工具）
提供IDE智能提示支持
作为代码内联文档

与普通注释(#)不同，Sphinx注释使用三重引号"""包裹，具有特定语法规则。

二、基本语法规则

模块级注释

python 复制代码

"""Module-level docstring.

This is a brief description of the module.
More detailed explanation goes here.
"""

类注释

python 复制代码

class MyClass:
    """Class-level docstring.

    Args:
        param1 (type): Description of param1
        param2 (type): Description of param2

    Attributes:
        attr1 (type): Description of attr1
    """

函数/方法注释

python 复制代码

def my_function(param1, param2):
    """Function-level docstring.

    Args:
        param1 (type): Description
        param2 (type): Description

    Returns:
        type: Description of return value

    Raises:
        ErrorType: When something bad happens
    """

三、核心字段说明

字段	用途	示例
`Args`	参数说明	`param1 (int): The first parameter`
`Returns`	返回值说明	`bool: True if successful`
`Raises`	可能抛出的异常	`ValueError: If input is invalid`
`Attributes`	类属性说明	`name (str): The name of instance`
`Examples`	使用示例	`>>> obj = MyClass()`
`Note`	重要说明	`Note: This is critical for...`
`.. versionadded::`	版本标记	`.. versionadded:: 1.2.0`

四、两种主流风格

Google风格（推荐）

python 复制代码

def add(a, b):
    """Add two numbers.

    Args:
        a (int or float): First number
        b (int or float): Second number

    Returns:
        int or float: Sum of a and b

    Example:
        >>> add(2, 3)
        5
    """
    return a + b

NumPy风格

python 复制代码

def subtract(a, b):
    """Subtract two numbers.

    Parameters
    ----------
    a : int or float
        First number
    b : int or float
        Second number

    Returns
    -------
    int or float
        Result of a - b
    """
    return a - b

五、实际应用示例

python 复制代码

class MolecularDataset:
    """AM1 molecular dataset handler.

    Args:
        data_path (str): Path to .pkl file
        max_atoms (int, optional): Max atoms per molecule. Defaults to 64.
        shuffle (bool, optional): Whether to shuffle data. Defaults to True.

    Attributes:
        elements (ndarray): Atomic numbers array
        coordinates (ndarray): 3D coordinates array

    Example:
        >>> dataset = MolecularDataset('data.pkl')
        >>> len(dataset)
        100
    """

    def __init__(self, data_path, max_atoms=64, shuffle=True):
        """Initialize with data path and parameters."""
        self.data_path = data_path
        self.max_atoms = max_atoms
        self.shuffle = shuffle

    def load(self):
        """Load molecular data from file.

        Returns:
            bool: True if loaded successfully

        Raises:
            FileNotFoundError: If data file doesn't exist
        """
        if not os.path.exists(self.data_path):
            raise FileNotFoundError
        return True

六、生成文档的步骤

安装Sphinx：

bash 复制代码

pip install sphinx sphinx-rtd-theme

创建文档项目：

bash 复制代码

sphinx-quickstart docs

配置docs/source/conf.py：

python 复制代码

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon'  # 支持Google/NumPy风格
]

编写.rst文件（如api.rst）：

rst 复制代码

API Reference
=============

.. automodule:: your_module
   :members:
   :show-inheritance:

生成HTML文档：

bash 复制代码

cd docs
make html

生成的文档将位于docs/_build/html目录，支持： • 自动参数类型链接

• 交互式示例代码

• 版本变更追踪

• 跨模块引用

七、IDE支持情况

IDE	功能支持
PyCharm	自动补全、悬浮提示、文档快速导航
VS Code	通过Python插件支持基本文档显示
Jupyter	使用`?`和`??`查看文档
Spyder	对象检查器(Object Inspector)显示完整文档