使用带有哨兵对象默认参数的Sphinx python方法进行文档记录？ [英] Documenting with Sphinx python methods that do have default parameters with sentinel objects?

问题描述

如果要允许人们使用 None 调用某些方法，则必须使用前哨对象。

If you want to be able to allow people to call some methods using None you have to do use a sentinel object when you define the method.

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

这将允许您调用 foo（param1 = None）并能够在像 foo（）之类的调用之间产生区别。

This would allow you to call foo(param1=None) and be able to make the difference between a call like foo().

问题在于Sphinx确实记录了该方法，它将编写类似的内容

The problem is that when Sphinx does document the method it will write something like

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

我如何说服Sphinx为这些功能提供用户友好的输出？

How can I convince Sphinx to have a user friendly output for these functions?

注意，想像一下如果使用哨兵方法有3-4个参数，文档的外观。

Note, Imagine how the documentations look if you have 3-4 parameters using the sentinel approach.

推荐答案

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

This can be handled by manually specifying function signature in autodoc directive, e.g.:

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words

这篇关于使用带有哨兵对象默认参数的Sphinx python方法进行文档记录？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！