Question

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

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

Answer 1

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

Answer 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:，这可能会误导读者。

Answer 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:

如何让Sphinx了解Sage的doctests？

3 个答案: