Sphinx浮点数格式化

Question

我正在使用Sphinx从代码生成文档。有人知道有没有办法控制从默认参数生成的浮点数的格式吗？

比如我有以下这个函数：

def f(x = 0.97):
    return x+1

生成的文档看起来是这样的：

foo(x = 0.96999999999997)

显然这是浮点数精度的问题，但有没有办法让文档看起来不那么难看呢？

Answer 1

我没有用过Sphinx，所以不确定这个方法是否有效，但我猜测repr()是用来决定文档格式的。你可以试着创建一个float的子类，并自定义一个__repr__方法，这样可以返回一个看起来更好看的数字，看看这样是否有帮助：

class my_float(float):
    def __repr__(self):
        return str(self)

>>> float(0.97)
0.96999999999999997
>>> my_float(0.97)
0.97

>>> def foo(x = my_float(0.97)):
...     return x+1
... 
>>> foo()
1.97

Answer 2

你可以用 .. autofunction:: 这个指令来覆盖一个函数的签名。举个例子，如果在模块 bar 中定义了一个函数 foo(x=0.97)：

.. automodule:: bar

   .. autofunction:: foo(x=0.97)

那么生成的文档会使用你提供的签名，而不是那个包含很长数字的解释版本。

你也可以用 .. autoclass:: 和 .. automethod:: 等类似的指令来做到这一点。这些用法在 sphinx.ext.autodoc 文档的“选项和高级用法”部分有详细说明。