将 Sphinx doctest 与 :Example 一起使用：

Question

考虑以下函数：

# in mymodule.py:

def myfunc(num,mystring):
    """
    replicates a string

    :param num: a positive integer
    :param mystring: a string
    :return: string concatenated with itself num times

    :Example:
        >>> num = 3
        >>> mystring = "lol"
        >>> myfunc(num, mystring)
            "lollollol"
    """
    return num*mystring

如何使 Sphinx doctest 工作，以验证

中的示例代码

:Example:´ actually does work? Whenever I run制作 doctest`

它说 3 个测试是运行，但是 1 个失败了。删除最后两行，从

开始

myfunc(num, mystring),

它说 2 个测试运行成功。所以我一定是在那条线上做错了什么。但是什么？

EDIT 这是完整代码的终端输出（回溯）；似乎不知何故它找不到我为其编写文档字符串的函数，我正在运行进行 doctest:

Running Sphinx v1.8.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [doctest]: targets for 1 source files that are out of date
updating environment: [] 0 added, 1 changed, 0 removed
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
running tests...

Document: index
---------------
**********************************************************************
File "index.rst", line ?, in default
Failed example:
    myfunc(num, mystring)
Exception raised:
    Traceback (most recent call last):
      File "/usr/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest default[2]>", line 1, in <module>
        myfunc(num, mystring)
    NameError: name 'myfunc' is not defined
**********************************************************************
1 items had failures:
   1 of   3 in default
3 tests in 1 items.
2 passed and 1 failed.
***Test Failed*** 1 failures.

Doctest summary
===============
    3 tests
    1 failure in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems.
Makefile:19: recipe for target 'doctest' failed

Answer 1

在我的终端和 Sphinx 外部，我必须左对齐 "lollollol" 并使用简单引号才能成功运行 doctest:

    :Example:
        >>> num = 3
        >>> mystring = "lol"
        >>> myfunc(num, mystring)
        'lollollol'

Answer 2

Sphinx+doctest 没有导入模块。您可以在文档字符串中帮助他：

    :Example:
        >>> from mymodule import myfunc
        >>> myfunc(3, 'lol')
        'lollollol'

或在 conf.py 中添加：

doctest_global_setup = '''
#if required, modif sys.path:
import sys
sys.path.append('../directory_containing_mymodule/')
from mymodule import *
'''

比照。 https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

我很想听听是否有更简单的答案。

Answer 3

正如 Demi-Lune 已经说过的，需要将 .py 文件的文件路径添加到 conf.py 文件中。但这不应该只传递给命令 doctest_global_setup='''.... import sys'''

而是通过声明

将其添加到一般conf.py路径设置中

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

替换为“.”通过你的绝对路径。（您也可以保留“.”并将您的 module.py 文件添加到您的 sphinx 项目的源文件夹中。尽管我不建议将此用于较大的项目。）

那么你只需要在conf.py文件中声明

doctest_global_setup='from module import *'

现在您可以在 module.py 函数中写入

def foo():
   '''
   >>>foo()
   ['bar','fafa','bara']
   '''
   return ['bar','fafa','bara']

为整个 conf.py 文件声明路径的好处是其他扩展程序（例如 autodoc）也可以检测到您的 module.py。在这种情况下，您只需要在 .rst 文件中写入

..autofunction:: module.foo()

它将从 module.py 获取 foo() 并执行 doctest 命令。希望能帮到你。

感谢 Demi-Lune!!!

将 Sphinx doctest 与 :Example 一起使用：

Use Sphinx doctest with :Example:

python

doctest

python-sphinx