Sphinx：如何包含位于模块内但在类和方法之外的文档字符串/注释

Question

我的 python 模块中有一条注释，记录了后面的几个类，例如

###

# Classes for agents: patients and clinicians

###

class EngagementLadder(transitions.Machine):
    """The state machine for agent states.

事实上有好几个这样的多类评论。每个都用于分解文件，将其组织成相关的部分。

我希望在生成的文档中看到这些注释，也许作为标题。如何做到这一点？

请注意，我的问题类似于 In Sphinx, how to include docstrings/comments located in a module, but externals of class andmethods,但答案对他有用——将其放入模块文档字符串中——对我来说不起作用，因为我希望这些评论在文件中更进一步。

Answer 1

实现此目的的一种方法是使用虚拟变量

即下面将添加一个章节标题

SECTION_A = "SECTION A"
"""Section A contains some useful stuff about my project...

It can span multiple lines...

"""

def foo():
    """Description of foo"""
    pass

#: Section B contains some useful stuff about my project...
#: It can span multiple lines
SECTION_B = "SECTION B"

def bar():
    """Description of foo"""
    pass

此处的文档：https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute

Answer 2

对于模块级注释，您可以添加到模块的 docstring 中。这将出现在模块生成的文档的开头

__doc__ = """This will appear as doc level comments in the sphinx output.

Continuation here...
"""

def example_fun(some_input: int, text_input: str = "") -> str:
    ...

__doc__ += "\n Can continue here, but it will also show up at doc level"

在 sphinx 中你会得到这样的东西：

<section id="module-sphinx_example">
<span id="sphinx-example-package"></span><h1>sphinx_example package<a class="headerlink" href="#module-sphinx_example" title="Link to this heading">¶</a></h1>
<p>This will appear as doc level comments in the sphinx output.</p>
<blockquote>
<div><p>Continuation here…</p>
</div></blockquote>
<p>Can continue here, but it will also show up at doc level</p>
<dl class="py class">
<dt class="sig sig-object py" id="sphinx_example.BaseClassEx">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">sphinx_example.</span></span><span class="sig-name descname"><span class="pre">BaseClassEx</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a_string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">int_with_def</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/sphinx_example.html#BaseClassEx"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#sphinx_example.BaseClassEx" title="Link to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Just a base class, not much to see here.</p>
<p>Note: the args for the constructor are listed as part of the class documentation and not the __init__. In fact,
unless you tell doc/src/conf.py to include the __init__ it will ignore them (and all the other dunter methods)</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>a_string</strong> (<em>str</em>) – Any old string will do</p></li>
<li><p><strong>int_with_def</strong> (<em>int</em><em>, </em><em>optional</em>) – Give me an int, or don’t that’s fine too. Defaults to 2.</p></li>
</ul>
</dd>
</dl>
</dd></dl>