只显示* docstring在Sphinx文档 [英] show *only* docstring in Sphinx documentation

问题描述

Sphinx有一个名为 automethod 的功能，它从方法的docstring中提取文档，并将其嵌入到文档中。但它不仅嵌入了docstring，而且嵌入了方法签名（name + arguments）。如何仅嵌入 docstring（不包括方法签名）？

Sphinx has a feature called automethod that extracts the documentation from a method's docstring and embeds that into the documentation. But it not only embeds the docstring, but also the method signature (name + arguments). How do I embed only the docstring (excluding the method signature)?

ref： http://sphinx.pocoo.org/ext/autodoc.html

推荐答案

我想你正在寻找的是：

from sphinx.ext import autodoc

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

autodoc.add_documenter(DocsonlyMethodDocumenter)

per 当前的源，这应该允许覆盖什么类负责记录方法（旧版本的 add_documenter 禁止这样的覆盖，但现在他们被明确允许）。 format_args return当然，在 autodoc 中记录的方式是不要打扰签名。

per the current sources this should allow overriding what class is responsible for documenting methods (older versions of add_documenter forbade such overrides, but now they're explicitly allowed). Having format_args return None, of course, is THE documented way in autodoc to say "don't bother with the signature".

我认为这是执行此任务的干净，架构化的方式，因此，优于monkeypatching替代方案。如果您需要使用一些旧版本的 sphinx ，但您可能确实需要monkeypatch（ autodoc.MethodDocumenter.format_args = lambda _：None - eek！ - ）虽然我建议将 sphinx 升级到当前版本，作为更好的方法，如果在您的具体部署中是可行的。

I think this is the clean, architected way to perform this task, and, as such, preferable to monkeypatching alternatives. If you need to live with some old versions of sphinx however you may indeed have to monkeypatch (autodoc.MethodDocumenter.format_args=lambda _:None -- eek!-) though I would recommend upgrading sphinx to the current version as a better approach if at all feasible in your specific deployment.

这篇关于只显示* docstring在Sphinx文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！