将 Sphinx doctest 与：示例一起使用：答案

【问题标题】：Use Sphinx doctest with :Example:将 Sphinx doctest 与：示例一起使用：
【发布时间】：2019-10-01 17:28:21
【问题描述】：

考虑以下函数：

# 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 runmake doctest`

它说运行了 3 次测试，但 1 次失败。删除最后两行，以

开头

myfunc(num, mystring),

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

EDIT 这是完整代码的终端输出（回溯）；似乎以某种方式找不到我为其编写文档字符串并且正在运行文档测试的函数：

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

【问题讨论】：

@mzjn 我附上了回溯

标签： python python-sphinx doctest

【解决方案1】：

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

如果有更简单的答案，我很想知道。

【讨论】：

这几乎成功了！ :Example: 中的导入有效，但如果我将其添加到 conf.py 则无效。我有什么可以让conf.py 工作的吗？
实际上有什么方法可以从我正在工作的文件夹中导入conf.py 中的所有内容，这样我就不会每次创建新模块并为函数/方法编写文档字符串在其中，我必须将它们添加到 conf.py?
您的模块是否已经打包（带有setup.py 和__init__.py）？ sphinx 可能不在包含mymodule.py 的文件夹中运行，因此您可能需要setup.py 或设置PYTHONPATH 以确保安全。
不，我的模块只是myproject 中的一个文件，而所有与Sphinx 相关的文件都在myproject/docs 中。我从来没有打包过一个模块（我也不知道如何处理PYTHONPATH），因为我对 Python 还很陌生；对不起:(
@l7ll7，PYTHONPATH（或 sys.path）告诉你的个人模块在哪里（当它们不在当前目录中时），例如：stackoverflow.com/questions/3402168/…

【解决方案2】：

在我的终端和 Sphinx 之外，我必须左对齐“lolollol”并使用简单的引号才能成功运行 doctest：

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

【讨论】：

不幸的是，它似乎也不起作用:(。我已经将回溯到我的问题。
正确的对齐方式和单引号确实是解决方案的一部分。在交互式会话中执行3 * "lol" 时，输出为'lollollol'。 Doctest 不接受 "lollollol" 作为预期输出。

【解决方案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 命令。希望我能帮上忙。

感谢半月！！！

【讨论】：