Sphinx缩进错误求助：base_model.py文档字符串格式问题

错误信息 #

1. 意外缩进

[{
"resource": "/c:/Users/User/Documents/GitHub/MIMIC/mimic/model_simulate/base_model.py",
"owner": "_generated_diagnostic_collection_name_#5",
"severity": 8,
"message": "Unexpected indentation.",
"source": "sphinx",
"startLineNumber": 46,
"startColumn": 1,
"endLineNumber": 47,
"endColumn": 1
}]

2. 定义列表未以空行结束；意外取消缩进

[{
"resource": "/c:/Users/User/Documents/GitHub/MIMIC/mimic/model_simulate/base_model.py",
"owner": "_generated_diagnostic_collection_name_#5",
"severity": 4,
"message": "Definition list ends without a blank line; unexpected unindent.",
"source": "sphinx",
"startLineNumber": 44,
"startColumn": 1,
"endLineNumber": 45,
"endColumn": 1
}]

3. 块引用未以空行结束；意外取消缩进

[{
"resource": "/c:/Users/User/Documents/GitHub/MIMIC/mimic/model_simulate/base_model.py",
"owner": "_generated_diagnostic_collection_name_#5",
"severity": 4,
"message": "Block quote ends without a blank line; unexpected unindent.",
"source": "sphinx",
"startLineNumber": 47,
"startColumn": 1,
"endLineNumber": 48,
"endColumn": 1
}]

原文档字符串 #

"""
    Abstract base class for creating and managing simulation models.

    This class serves as a foundation for any type of model that requires
    managing data, parameters, and basic I/O operations. It defines a
    common interface for parameter handling, data simulation, and data
    persistence.

    Attributes:
        data (np.ndarray | None): Holds the output data generated by the model's simulation.
            This could be None if the model has not yet produced any data.
        model (object | None): A generic placeholder for the specific simulation model instance.
            This attribute should be overridden in subclasses with an actual
            model representation.
        parameters (dict | None): A dictionary containing the parameters that control the model's
            behavior. Parameters should be defined in subclasses or set through
            the provided methods.

    Abstract Methods:
        set_parameters(self): Should be implemented by subclasses to define how model parameters
            are set or updated.
        simulate(self): Should be implemented by subclasses to define the model's simulation process
            based on the set parameters.

    Methods:
        check_params(self, params, sim_type): Checks provided parameters against required ones for a
            given simulation type, applying default values if necessary.
        read_parameters(self, filepath): Reads model parameters from a specified JSON file and updates
            the model's parameters accordingly.
        save_parameters(self, filepath, parameters=None): Saves the model's current parameters to a
            JSON file. Optionally, a specific set of parameters can be provided to save instead.
        print_parameters(self, precision=2): Prints the current set of model parameters to the console,
            formatting numpy arrays with specified precision.
        save_data(self, filename, data=None): Saves the model's generated data to a CSV file. Optionally,
            specific data can be provided to save instead.
        load_data(self, filename): Loads data from a specified CSV file into the model's `data` attribute.
        _custom_array_to_string(self, array, precision=2): Converts a numpy array to a string representation
            with specified precision.
        update_attributes(self): Updates class attributes based on the current parameters dictionary.
    """

修正后的文档字符串 #

"""
    Abstract base class for creating and managing simulation models.

    This class serves as a foundation for any type of model that requires
    managing data, parameters, and basic I/O operations. It defines a
    common interface for parameter handling, data simulation, and data
    persistence.

    Attributes:
        data (np.ndarray | None): Holds the output data generated by the model's simulation.
            This could be None if the model has not yet produced any data.
        model (object | None): A generic placeholder for the specific simulation model instance.
            This attribute should be overridden in subclasses with an actual
            model representation.
        parameters (dict | None): A dictionary containing the parameters that control the model's
            behavior. Parameters should be defined in subclasses or set through
            the provided methods.

    Abstract Methods:
        set_parameters(self): Should be implemented by subclasses to define how model parameters
            are set or updated.
        simulate(self): Should be implemented by subclasses to define the model's simulation process
            based on the set parameters.

    Methods:
        check_params(self, params, sim_type): Checks provided parameters against required ones for a
            given simulation type, applying default values if necessary.
        read_parameters(self, filepath): Reads model parameters from a specified JSON file and updates
            the model's parameters accordingly.
        save_parameters(self, filepath, parameters=None): Saves the model's current parameters to a
            JSON file. Optionally, a specific set of parameters can be provided to save instead.
        print_parameters(self, precision=2): Prints the current set of model parameters to the console,
            formatting numpy arrays with specified precision.
        save_data(self, filename, data=None): Saves the model's generated data to a CSV file. Optionally,
            specific data can be provided to save instead.
        load_data(self, filename): Loads data from a specified CSV file into the model's `data` attribute.
        _custom_array_to_string(self, array, precision=2): Converts a numpy array to a string representation
            with specified precision.
        update_attributes(self): Updates class attributes based on the current parameters dictionary.

    """

错误原因及修正说明 #

Sphinx基于reStructuredText解析文档字符串，对定义列表（如Attributes、Abstract Methods、Methods这类区块）的格式要求严格：

• 定义列表的最后一项描述结束后，必须添加空行再闭合文档字符串，否则解析器会误判缩进层级，触发"定义列表未结束""意外缩进"类错误。
• 原文档中最后一个方法的描述直接跟在闭合的"""前，缺少空行，导致Sphinx无法正确识别定义列表的结束位置，进而引发所有缩进报错。
• 只需在最后一个方法的描述与"""之间添加一行空行，即可解决所有问题。

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