Question

在记录模块变量json_class_index（请参阅source）时遇到以下错误，该变量没有文档字符串。

生成的文档seems to be fine。什么是好的解决方案？

reading sources... [100%] sanskrit_data_schema_common                                                                                                                                               
/home/vvasuki/sanskrit_data/sanskrit_data/schema/common.py:docstring of sanskrit_data.schema.common.json_class_index:3: WARNING: Unexpected indentation.
/home/vvasuki/sanskrit_data/sanskrit_data/schema/common.py:docstring of sanskrit_data.schema.common.json_class_index:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/vvasuki/sanskrit_data/sanskrit_data/schema/common.py:docstring of sanskrit_data.schema.common.json_class_index:7: WARNING: Unexpected indentation.
/home/vvasuki/sanskrit_data/sanskrit_data/schema/common.py:docstring of sanskrit_data.schema.common.json_class_index:8: WARNING: Inline strong start-string without end-string.

编辑： PS：请注意，删除下面的docstring会使错误消失，因此似乎需要修复。

.. autodata:: json_class_index
  :annotation: Maps jsonClass values to Python object names. Useful for (de)serialization. Updated using update_json_class_index() calls at the end of each module file (such as this one) whose classes may be serialized.

Answer 1

警告消息表明文档字符串的reStructuredText语法无效，需要更正。

此外，您的源代码不符合PEP 8. Indentation should be 4 spaces，但您的代码使用2，这可能会导致Sphinx出现问题。

首先使您的代码符合PEP 8缩进。

其次，您必须有两行分隔信息字段列表和信息字段列表之前的任何内容。

第三，如果警告仍然存在，那么请查看警告-3,4,7和8中的行号以及警告本身。警告似乎与this block of code：

相对应

  @classmethod
  def make_from_dict(cls, input_dict):
    """Defines *our* canonical way of constructing a JSON object from a dict.

    All other deserialization methods should use this.
    Note that this assumes that json_class_index is populated properly!
      - ``from sanskrit_data.schema import *`` before using this should take care of it.
    :param input_dict:
    :return: A subclass of JsonObject
    """

尝试使用后PEP-8 -ification，这应该可以纠正文档字符串中错误的空白区域引起的大多数警告：

@classmethod
def make_from_dict(cls, input_dict):
    """
    Defines *our* canonical way of constructing a JSON object from a dict.

    All other deserialization methods should use this.

    Note that this assumes that json_class_index is populated properly!

    - ``from sanskrit_data.schema import *`` before using this should take care of it.

    :param input_dict:
    :return: A subclass of JsonObject
    """

根据PEP 257，这种风格是可以接受的。压痕在视觉上和垂直上是一致的，其中三引号与左压痕垂直对齐。我觉得它更容易阅读。

Answer 2

修复方法是为变量添加docstring，如下所示：

#: Maps jsonClass values to Python object names. Useful for (de)serialization. Updated using update_json_class_index() calls at the end of each module file (such as this one) whose classes may be serialized.
json_class_index = {}

模块变量文档错误

2 个答案: