使用带有哨兵对象的默认参数的 Sphinx python 方法进行记录？

Question

如果您希望能够允许人们使用 None 调用某些方法，您必须使用 sentinel 对象。

 _sentinel = object()
 def foo(param1=_sentinel):
     ...

这将允许您调用 foo(param1=None) 并能够区分 foo() 等调用。

问题是，当 Sphinx 记录该方法时，它会编写类似“

mymodule.foo(param1=<object object at 0x108c1a520>)

我怎样才能说服 Sphinx 为这些函数提供用户友好的输出？”

之类的内容。请注意，想象一下，如果您使用哨兵方法有 3-4 个参数，文档会是什么样子。

Answer 1

生成的方法签名的

_sentinel = type('_sentinel', (object,),
                 {'__repr__': lambda self: '_sentinel'})()

Sphinx 会将其渲染为如下所示：

mymodule.foo(param1=_sentinel)

Answer 2

我认为只要你有一个在函数之外创建对象的哨兵，就不可能说服 Sphinx 变得更加“友好”。 Sphinx的autodoc扩展导入模块，这意味着执行模块级代码。

你确定你不能使用这样的东西吗？

def foo(param1=None):
    if param1 == None:
        param1 = whatever you want...
    else:
         ... 

Answer 3

这可以通过在 autodoc 指令中手动指定函数签名来处理，例如：

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words