我开始用Sphinx记录我的第一个基于异步的项目。我注意到有些项目在某些方法之前带有“协程”前缀，我想在我的项目文档中做同样的事情，但是我不知道怎么做。
例如，aiohttp's HTTP client reference显示如下：
类aiohttp.ClientSession（...）：
协程request（...）
该项目似乎使用coroutinemethod指令来实现此目的，但是我使用docstrings内联记录了我的所有函数和类，并且仅当您在reStructuredText文档中编写文档时，此指令才有效。
有人知道如何使用autodoc达到此结果吗？
编辑：我还将接受回答，这些回答解释了如何在Sphinx不支持的情况下进行Sphinx扩展。如果有人可以将my指向某种使用inspect.iscoroutinefunction()自动检测该方法是否为协程的方法，则该方法会给您带来加分。
编辑：我正在寻找CPython项目中的"pyspecific" Sphinx extension以获取灵感。但是，我需要更改autodoc的行为，而不是添加新的指令。经过一番研究，看来autodoc有一个autodoc-process-signature event可用于自定义函数签名，但似乎没有“ pyspecific”扩展使用的对象。
最佳答案
Sphinx还没有内置此功能。但是，pull request #1826在autodoc的autofunction和automethod指令中添加了对生成器，协程函数，具有协程内置检测功能的协程方法的支持。
这是我在本地应用的补丁，用于在Sphinx 1.4中启用此功能（需要禁用sphinx-build的-W“将警告变为错误”选项）：
# Recipe stolen from open PR (https://github.com/sphinx-doc/sphinx/pull/1826).
from inspect import iscoroutinefunction
from sphinx import addnodes
from sphinx.domains.python import (
PyClassmember,
PyModulelevel,
)
from sphinx.ext.autodoc import FunctionDocumenter as _FunctionDocumenter
from sphinx.ext.autodoc import MethodDocumenter as _MethodDocumenter
class PyCoroutineMixin(object):
"""Helper for coroutine-related Sphinx custom directives."""
def handle_signature(self, sig, signode):
ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
return ret
class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
"""Sphinx directive for coroutine functions."""
def run(self):
self.name = 'py:function'
return PyModulelevel.run(self)
class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
"""Sphinx directive for coroutine methods."""
def run(self):
self.name = 'py:method'
return PyClassmember.run(self)
class FunctionDocumenter(_FunctionDocumenter):
"""Automatically detect coroutine functions."""
def import_object(self):
ret = _FunctionDocumenter.import_object(self)
if not ret:
return ret
obj = self.parent.__dict__.get(self.object_name)
if iscoroutinefunction(obj):
self.directivetype = 'coroutine'
self.member_order = _FunctionDocumenter.member_order + 2
return ret
class MethodDocumenter(_MethodDocumenter):
"""Automatically detect coroutine methods."""
def import_object(self):
ret = _MethodDocumenter.import_object(self)
if not ret:
return ret
obj = self.parent.__dict__.get(self.object_name)
if iscoroutinefunction(obj):
self.directivetype = 'coroutinemethod'
self.member_order = _MethodDocumenter.member_order + 2
return ret
def setup(app):
"""Sphinx extension entry point."""
# Add new directives.
app.add_directive_to_domain('py', 'coroutine', PyCoroutineFunction)
app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
# Customize annotations for anything that looks like a coroutine.
app.add_autodocumenter(FunctionDocumenter)
app.add_autodocumenter(MethodDocumenter)
# Return extension meta data.
return {
'version': '1.0',
'parallel_read_safe': True,
}