相关疑难解决方法(0)

我正在使用Sphinx的autodoc插件自动记录一组模块.我有一个接受的函数,*args我想覆盖文档以显示funcname(arg1[, arg2[, ...]])Python stdlib文档使用的稍微好一点的样式.

是否可以覆盖特定功能的autodoc输出？

我正在使用Sphinx的autodoc功能来记录我的API.

例:

DEFAULT_OPTION = 'default'
def do_something(msg, option=DEFAULT_OPTION):
    print msg

生成的文档现在显示以下签名:

do_something(msg, option='default')

如何告诉Sphinx保留常量值的名称,即

do_something(msg, option=DEFAULT_OPTION)

？

有没有我忽略的选择？如果可能的话,我不想再用手写所有的签名.

假设我有这样一个类:

class MyClass(object):
    """ Summary docs for my class.

    Extended documentation for my class.
    """

    def __init__(self, *args):
        self.values = np.asarray(args)

如果我使用带有autodoc扩展名的Sphinx 来记录这个类,如下所示:

.. automodule:: mymodule
   :members:

...构造函数签名显示为MyClass(*args).我宁愿覆盖它并将其记录为,比方说MyClass(first, second, third).

如果这是一个函数,我可以覆盖docstring第一行中的签名.但是这个技巧似乎不适用于类docstring.那么如何覆盖构造函数签名呢？

当autodoc在它生成的文档中列出类型时，例如Bases类继承自的类型，或函数参数的类型提示，它会添加类型的模块。例如，接收 Tensorflow Optimizer 的函数将被列为

f(opt: tensorflow.python.training.optimizer.Optimizer = <tensorflow.python.training.adam.AdamOptimizer object>)

这真的很难读而且是多余的。有没有办法抑制在模块名称之前添加？或者另一种控制类型如何列出的方法？

编辑： 这个答案有助于一次修复这个功能。有没有办法为所有功能解决这个问题？

鉴于模块中的以下函数，mymodule我想使用 Sphinx 进行记录autodoc：

from typing import Union\nfrom collections.abc import Iterable\nfrom numpy.typing import ArrayLike\n\ndef foo(a: Union[str, int], b: Iterable, c: ArrayLike) -> None:\n    """Do something useful."""\n    pass\n

在源代码中，函数的签名非常可读。但是，在生成的文档中autodoc但是，在签名

\n

khadl._util.foo（a：Union [str，int]，b：collections.abc.Iterable，c：Union [int，float，complex，str，字节，numpy.generic，Sequence [Union [int，float，complex] , str, bytes, numpy.generic]], 序列[序列[任意]], numpy.typing._array_like._SupportsArray]) \xe2\x86\x92 无

\n

这是不可读的。源自模块的类typing以简短形式显示（Union, Sequence, Any），但对于抽象基类，Iterable会生成唯一标识符（collections.abc.Iterable），ArrayLike甚至“解包”（Union[int, float, complex, str, bytes, numpy.generic, Sequence[Union[int, float, complex, str, bytes, numpy.generic]], Sequence[Sequence[Any]], …