Sphinx-autodoc with napoleon（Google 文档字符串样式）：有关块引用和缩进的警告和错误

发布于 2025-01-12 13:53:13 字数 1667 浏览 0 评论 0 原文

我正在使用 Sphinx 4.4.0 和 napoleon 扩展（Google 文档字符串）。我有这两个问题

ARNING：块引用结束时没有空行；意外的未缩进。
错误：意外的缩进。

我在互联网上找到了一些有关它的信息，但无法适应这两个我的代码。我的问题是我什至不理解这些消息。我不明白问题出在哪里。

这是代码：

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.

原文

I am using Sphinx 4.4.0 with napoleon extension (Google Doc String). I have this two problems

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

I found something about it on the internet but can not fit this two my code. My problem is I even do not understand the messages. I do not see where the problem could be.

This is the code:

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.

    """

This are the original messages:

.../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.

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

情话难免假 2025-01-19 13:53:13

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.

    """

reStructuredText is not Markdown, and indentation alone is not enough to demarcate the code block. reStructuredText calls this a literal block. Although the use of :: is one option, you might want to explicitly specify the language (overriding the default) with the use of the code-block directive.

Also I noticed that you have invalid syntax in your code block—a missing ) and extra spaces in your indentation—which could have caused those errors.

Try this.

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.

    """

回复收藏 0 原文

~没有更多了~