模块变量文档错误

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: 请注意，删除下面的文档字符串会使错误消失，所以它似乎是要解决的问题。

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

试试这个，post-PEP-8-ification，它应该纠正大部分由你的文档字符串中错误的白色 space 引起的警告：

@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

修复方法是为变量添加文档字符串，如下所示：

#: 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 = {}

模块变量文档错误

Module variable documentation error

python-sphinx