我使用 Sphinx 和自动文档功能来确保我们的项目中有良好的文档。
所以我很熟悉信息字段列表 http://sphinx-doc.org/domains.html#info-field-lists我熟悉使用交叉引用 http://sphinx-doc.org/domains.html#cross-referencing-python-objects在我们的文档中。
但是,在为方法或函数编写文档字符串时,我发现在文本中引用它们的参数很有用。但似乎没有一种结构化的方法可以做到这一点。
-
我们可以说,例如
Use ``name`` to set the username
但这没有结构,需要你记住你使用的样式,如果你改变样式,你必须寻找并杀死所有不正确的样式。
-
:param: 在信息字段列表之外不起作用,因此您无法写入
Use :param:`name` to set the username
我见过一些项目使用 :parm: 但这没有记录并且似乎不起作用。所以他们必须有一些定制
- 我可以使用 generic_roles 但这似乎是我在解决一个我确信其他人也遇到过的问题。
所以希望我只是错过了一些非常明显的事情。
您可以使用编写自己的扩展自动文档流程文档字符串 http://sphinx-doc.org/ext/autodoc.html?highlight=autodoc#event-autodoc-process-docstring- 这真的很简单。
让扩展名搜索:param:
并将其替换为您选择的样式。
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)