在Sphinx文档中显示* only *文档字符串？ [英] Show *only* docstring in Sphinx documentation?

问题描述

Sphinx具有一项称为 automethod 的功能，该功能可从方法的文档字符串中提取文档并将其嵌入到文档中。但是它不仅嵌入了文档字符串，而且还嵌入了方法签名（名称和参数）。如何仅在文档字符串中嵌入 （不包括方法签名）？

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

推荐答案

我认为您正在寻找的是：

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)

每个当前来源，这应允许覆盖负责记录方法的类（旧版本的 add_documenter 禁止此类替代，但现在明确允许使用。 format_args 返回无，当然是 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".

我认为这是执行此任务的干净，结构化的方式，因此，比选择猴子补丁更可取。如果您需要使用某些旧版本的 sphinx ，则可能确实需要进行猴子补丁（ 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.

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