模塊變量文檔錯誤

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

此修復程序是添加一個文檔字符串的變量，如下所示：

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

Answer 2

警告消息指出您的文檔字符串的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，此款式可以接受。縮進在視覺上和垂直方向上一致，其中三引號與左縮進垂直對齊。我認爲閱讀起來比較容易。