在 Sphinx 文档中显示 *only* 文档字符串？

Question

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://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Answer 1

I think what you're looking for is:

from sphinx.ext import autodoc

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

autodoc.add_documenter(DocsonlyMethodDocumenter)

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".

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.