如何让 Sphinx 理解 Sage 文档测试？答案

【问题标题】：How to make Sphinx understand Sage doctests?如何让 Sphinx 理解 Sage 文档测试？
【发布时间】：2014-04-24 16:05:40
【问题描述】：

我有一个主要是 Python 的包，主要用于 Python。但在 Sage 下使用该模块时，还有一些额外的功能可用。问题是 Sage doctests 必须以 sage: 而不是 >>> 为前缀，而 Sphinx 在生成文档时不会选择这些。

在生成 HTML（或其他）文档时，有没有办法让 Sphinx 将 sage: 前缀识别为等同于 >>>？

【问题讨论】：

你能说一下你是如何调用 Sphinx 的吗？我可能想尝试一下。
我刚刚运行了sphinx-quickstart，它设置了conf.py 和Makefile，因此您可以执行make clean && make html。它会问一些问题，最好告诉它使用doc 目录，否则它会污染你的项目目录。如果您想直接试验我的项目，它是 GitHub 上的 qitensor，我已经使用我在下面的回答中提到的 hack 修改了 conf.py。

标签： python python-sphinx sage doctest

【解决方案1】：

好吧，您可以使用 Sage 的 Sphinx 内置版本及其文档构建器。在http://trac.sagemath.org/ticket/13679 为 Sage 进行的工作允许为单个 Python 文件构建文档，该文件不在 Sage 的源代码树中，因此您可以尝试这样做。

【讨论】：

Sage 的sphinx-build 在这种情况下不起作用，因为我的 Cython 文件是针对系统的库而不是 Sage 的库编译的。此外，即使用户没有 Sage，我也非常希望允许构建文档。
尝试查看 Sage 的 conf.py（在 sage/doc/common 中）看看是否有帮助。 Sphinx 的quickstart.py 中也有一行：PROMPT_PREFIX = '> '。您可以尝试修改它，看看会发生什么。
我认为魔法被深深地埋藏在圣人的深处。 sage/doctest/parsing.py 中有一些东西，但不清楚它是如何连接的。有趣的是，为['"]>>> grepping Sphinx 只会出现highlighting.py 并且修改它并不能解决问题。也许doctest 或pygments 中的某些内容是相关的。

【解决方案2】：

我终于找到了如何预处理文档字符串，将sage: 更改为>>>。以下内容进入我项目的doc/conf.py：

# Adapted from http://stackoverflow.com/a/11746519/1048959
def process_docstring(app, what, name, obj, options, lines):
    for i in range(len(lines)):
        lines[i] = re.sub(r'^(\s*)sage: ', r'\1>>> ', lines[i])

def setup(app):
    app.connect('autodoc-process-docstring', process_docstring)

至少现在 Sphinx 可以解析我的文档字符串而不会产生错误。我仍然没有解决这个问题，因为仍然存在问题：生成的文档显示>>> 而不是sage:，这可能会误导读者。

【讨论】：

【解决方案3】：

好的，这是另一个想法：尝试在缩进的块前面加上双冒号。例如，在 slices.rst 中，改变

You can use numpy style indexes:

    >>> x[0, 0]
    0j

到

You can use numpy style indexes::

    sage: x[0, 0]
    0j

（我添加了双冒号，并将提示更改为sage:。）我用你的代码尝试了这个，但是注释掉你对conf.py的修改。源代码块见the Sphinx docs。

那么你需要修改一个Sphinx文件：

diff -ur sphinx/highlighting.py sphinx/highlighting.py
--- sphinx/highlighting.py  2010-08-11 17:17:48.000000000 +0200
+++ sphinx/highlighting.py  2010-11-28 12:04:44.068642703 +0100
@@ -161,7 +161,7 @@

         # find out which lexer to use
         if lang in ('py', 'python'):
-            if source.startswith('>>>'):
+            if source.startswith('>>>') or source.startswith('sage: '):
                 # interactive session
                 lexer = lexers['pycon']
             else:

【讨论】：

谢谢。似乎这会产生这些文档测试未运行的副作用，对吗？理想情况下，我希望在 sage 中安装时运行 sage: doctests。另外，我试图避免对 Sphinx 进行猴子补丁。但也许如果找到一个好的解决方案，可以向他们提交补丁。
如果您执行sage -t FILE，Sage 应该运行这些文档测试。这就是 Sage 的所有文档测试的格式。
好的，那么双冒号不会使文档测试不可见吗？一旦我可以让它在 sage 中运行，我会尽快测试它（它现在给了我一个 numpy.ufunc has the wrong size, try recompiling，我不知道为什么；sage 是编译 cython 的那个）。