当使用Sphinx记录时，省略（或格式化）变量的值 [英] Omit (or format) the value of a variable when documenting with Sphinx

问题描述

我正在使用 autodoc 。但是，我在模块级别定义了包含长列表或列表的几个变量。它们被包含在文档中与值一起，并且值是未格式化的，所以它看起来像一个10行的混乱。我想要的是要包含这些变量的docstring，但是要忽略或至少格式化的值。

我试图排除变量从 automodule 指令，并添加它：

  .. automodule： ：foo.bar 
：成员：
：exclude-members：longstuff 
 
 .. py：data :: longstuff 
  pre> 
 
 
这导致只包含变量名，而docstring和 longstuff 的值分别为不存在于文档中。
 
 
 
如何保持文本字符串并摆脱该值（或格式化好）？感谢提前。
解决方案
没有简单的配置设置，省略输出中的模块级变量的值。但是您可以通过修改 DataDocumenter.add_directive_header（）方法来执行此操作/ext/autodoc.pyrel =nofollow> autodoc.py 。该方法中的关键线是
  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）
＃忽略原始方法的剩余
 
 DataDocumenter.add_directive_header = add_directive_header 
  
 
I'm currently documenting a whole module with autodoc. However, I define several variables on the module level that contain long lists or dicts. They are included in the documentation together with the values, and the values are unformatted, so it looks like a 10-lines mess. What I want is for the docstring of those variables to be included, but for the values to be omitted or at least nicely formatted.

I've tried to exclude the variable from automodule directive and add it like that:
.. automodule:: foo.bar
   :members:
   :exclude-members: longstuff

   .. py:data:: longstuff
This resulted in that only the variable name was included, whereas both the docstring and the value of longstuff were not present in the documantation.

How can I keep the docstring and get rid of the value (or have it nicely formatted) at the same time? Thanks in advance.
解决方案
There is no simple configuration setting for omitting values of module level variables in the output. But you can do it by modifying the DataDocumenter.add_directive_header() method in autodoc.py. The crucial line in that method is
self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')
where objrepr is the value.

The following monkey patch added to conf.py works for me:
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


                        
这篇关于当使用Sphinx记录时，省略（或格式化）变量的值的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！