在 Sphinx 中将特定方法或函数参数标记为已弃用答案

【问题标题】：Mark a specific method or function parameter as deprecated in Sphinx在 Sphinx 中将特定方法或函数参数标记为已弃用
【发布时间】：2020-09-15 12:47:34
【问题描述】：

我正在使用 Sphinx 来记录一个 python 3 类，并且该类中的某些方法具有不再使用的参数值。将这些标记为不推荐使用的参数的最佳方法是什么？有在线文档提到将整个方法标记为已弃用，但我没有找到继续有效但参数已更改的方法。在我的情况下，将这些参数标记为仅关键字可能会有所帮助。

补充：我是这样声明参数的：

Some function description

:param bool param_a: If True, do something.
:param bool param_b: Deprecated since 0.2.4 - how should I mark this?
:return: An integer.
:rtype: int

【问题讨论】：

标签： parameters python-sphinx deprecated

【解决方案1】：

Steve Piercy 在 sphinx v4 中为我发布了已弃用的指令：

:param str myparam:
    Description of my param

    .. deprecated:: 1.1
        Use mynewparam instead

info field lists 文档中并没有特别清楚地说明参数的描述可以是多行的，但它们可以是。

【讨论】：

【解决方案2】：

使用deprecated directive。

.. deprecated:: 3.1
    Use ``arg`` instead.

【讨论】：

那里的例子似乎暗示它可能用于整个函数或方法。有没有办法（或示例）记录已弃用的参数，但也将其标记为已弃用？
这取决于你是否记录你的参数。如果你这样做了，那么把指令放在你记录它们的地方。
我已添加到问题中以显示我如何记录参数。我不知道如何在其中挤压.. deprecated:: 指令？
这行不通，因为在该上下文中仅支持文本，不支持解析。我的意思更像是 docs.pylonsproject.org/projects/pyramid/en/latest/api/… 及其源文档字符串 docs.pylonsproject.org/projects/pyramid/en/latest/_modules/…（滚动到结尾）。
你试过什么？请编辑您的答案。如果field list 中的参数描述包含块语法，我认为它不能被解析为reStructuredText，但您可以尝试，确保使用正确的缩进。它可能能够解析内联语法，例如:term:。