python - 在 Sphinx 文档中显示*仅*文档字符串？

Question

Sphinx 有一个名为 automethod 的功能，它可以从方法的文档字符串中提取文档并将其嵌入到文档中。但它不仅嵌入了文档字符串，还嵌入了方法签名(名称+参数)。如何仅嵌入文档字符串(不包括方法签名)？

引用:http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Answer 1

我想你要找的是:

from sphinx.ext import autodoc

class DocsonlyMethodDocumenter(autodoc.MethodDocumenter):
  def format_args(self):
    return None

autodoc.add_documenter(DocsonlyMethodDocumenter)

根据 the current sources这应该允许覆盖负责记录方法的类(旧版本的 add_documenter 禁止此类覆盖，但现在明确允许)。让 format_args 返回 None，当然，autodoc 中记录的方式是说“不要打扰签名”。

我认为这是执行此任务的干净、架构化的方式，因此比 monkeypatching 替代方案更可取。如果你需要使用一些旧版本的 sphinx 但是你可能确实需要 monkeypatch (autodoc.MethodDocumenter.format_args=lambda _:None -- eek!-)如果在您的特定部署中完全可行，我建议将 sphinx 升级到当前版本，这是一种更好的方法。