Sphinx autodoc with napleon(谷歌文档字符串样式):关于块引号和缩进的警告和错误

Question

我使用的是带有napleon扩展名的Sphinx 4.4.0(Google Doc String(。我有两个问题

• ARNING: Block quote ends without a blank line; unexpected unindent.
• ERROR: Unexpected indentation.

我在网上找到了一些关于它的东西，但我的代码无法容纳这两个。我的问题是我甚至不理解这些信息。我看不出问题出在哪里。

这是代码：

def read_and_validate_csv(basename, specs_and_rules):
"""Read a CSV file with respect to specifications about format and
rules about valid values.
Hints: Do not use objects of type type (e.g. str instead of "str") when
specificing the column type.
specs_and_rules = {
'TEMPLATES': {
'T1l': ('Int16', [-9, ' '])
},
'ColumnA': 'str',
'ColumnB': ('str', 'no answer'),
'ColumnC': None,
'ColumnD': (
'Int16',
-9, {
'len': [1, 2, (4-8)],
'val': [0, 1, (3-9)]
}
}
Returns:
(pandas.DataFrame): Result.
"""

这是原始消息：

.../bandas.py:docstring of buhtzology.bandas.read_and_validate_csv:11: WARNING: Block quote ends without a blank line; unexpected unindent.
.../bandas.py:docstring of buhtzology.bandas.read_and_validate_csv:15: ERROR: Unexpected indentation.
.../bandas.py:docstring of buhtzology.bandas.read_and_validate_csv:17: ERROR: Unexpected indentation.
.../bandas.py:docstring of buhtzology.bandas.read_and_validate_csv:19: WARNING: Block quote ends without a blank line; unexpected unindent.
.../bandas.py:docstring of buhtzology.bandas.read_and_validate_csv:20: WARNING: Block quote ends without a blank line; unexpected unindent.

Answer 1

reStructuredText不是Markdown，仅缩进不足以划分代码块。reStructuredText将其称为文字块。尽管使用::是一个选项，但您可能希望使用code-block指令显式指定语言(覆盖默认值(。

我还注意到，您的代码块中有无效语法——缺少)，缩进中有多余的空格——这可能会导致这些错误。

试试这个。

def read_and_validate_csv(basename, specs_and_rules):
"""Read a CSV file with respect to specifications about format and
rules about valid values.
Hints: Do not use objects of type type (e.g. str instead of "str") when
specificing the column type.
..  code-block:: python
specs_and_rules = {
'TEMPLATES': {
'T1l': ('Int16', [-9, ' '])
},
'ColumnA': 'str',
'ColumnB': ('str', 'no answer'),
'ColumnC': None,
'ColumnD': (
'Int16',
-9, {
'len': [1, 2, (4-8)],
'val': [0, 1, (3-9)]
}
)
}
Returns:
(pandas.DataFrame): Result.
"""