使用 Sphinx 记录时省略（或格式化）变量的值答案

【问题标题】：Omit (or format) the value of a variable when documenting with Sphinx使用 Sphinx 记录时省略（或格式化）变量的值
【发布时间】：2020-04-07 07:03:50
【问题描述】：

我目前正在使用autodoc 记录整个模块。但是，我在模块级别定义了几个包含长列表或字典的变量。它们与值一起包含在文档中，并且值未格式化，因此看起来像 10 行混乱。我想要的是包含这些变量的文档字符串，但要省略这些值或至少格式化。

我试图从automodule 指令中排除变量并像这样添加它：

.. automodule:: foo.bar
   :members:
   :exclude-members: longstuff

   .. py:data:: longstuff

这导致仅包含变量名称，而文档字符串和 longstuff 的值都没有出现在文档中。

我怎样才能同时保留文档字符串并删除该值（或将其格式化）？

【问题讨论】：

标签： python documentation python-sphinx autodoc

【解决方案1】：

没有用于在输出中省略模块级变量值的简单配置设置。但是你可以通过修改autodoc.py中的DataDocumenter.add_directive_header()方法来实现。该方法的关键是

self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')

其中objrepr 是值。

添加到 conf.py 的以下猴子补丁适用于我：

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter

def add_directive_header(self, sig):
    ModuleLevelDocumenter.add_directive_header(self, sig)
    # Rest of original method ignored

DataDocumenter.add_directive_header = add_directive_header

【讨论】：

另一方面，如果我只是重新制作页面，则不会发生更改，但前提是我更改了页面源中的某些内容。它经常发生并且很烦人。这很常见吗？确保应用更改的最简单方法是什么？看起来它假设如果源完好无损，则不需要进行任何更改，这是错误的。
我不确定我是否理解。我使用make clean html 来确保一切从头开始。
我想这就是我需要的。抱歉这个愚蠢的问题，除了 Sphinx 文档之外，我只是碰巧不经常使用 make :)
为我工作。请注意，如果您希望这仅适用于特定符号，则必须编写一个更高级的函数来检查 self.name 并在名称不匹配时委托给原始方法。