python - 在 Python 文档字符串中引用参数

Question

我使用 Sphinx 和 autodocs 功能来确保我们的项目中有好的文档。

所以我熟悉信息字段列表，也熟悉在我们的文档中使用交叉引用。

但是，在为方法或函数编写文档字符串时，我发现在文本中引用它们的参数很有用。但似乎没有一种结构化的方式来做到这一点。

1. 我们可以说例如

   Use ``name`` to set the username
   

   但这没有结构，需要你记住你使用的风格，如果你改变风格，你必须追捕并杀死所有不正确的风格。

2. :param: 在信息字段列表之外不起作用，所以你不能写

   Use :param:`name` to set the username
   

3. 我已经看到一些项目使用 :parm: 但这没有记录并且似乎不起作用。所以他们必须有一些定制

4. 我可以使用 generic_roles，但这似乎是我在解决我确信其他人遇到的问题。

所以希望我刚刚错过了一些非常明显的东西。

Answer 1

您可以使用autodoc-process-docstring编写自己的扩展- 这非常简单。

让扩展程序搜索:param:并用您选择的样式替换它。