我有一个主要使用Python编写的软件包，大部分是为Python使用而设计的。但是，在Sage下使用该模块时还有一些额外的函数可用。问题是，Sage doctest必须以为前缀，而不是<>>>，而Sphinx在生成文档时无法识别这些内容。
是否有办法让Sphinx在生成HTML（或其他）文档时将前缀识别为与<>>>等效？
是否有办法让Sphinx在生成HTML（或其他）文档时将前缀识别为与<>>>等效？
3个回答
2
你可以使用Sage内置的Sphinx版本和文档生成器。Sage正在进行工作，在http://trac.sagemath.org/ticket/13679上允许构建单个Python文件的文档，该文件不在Sage的源代码树中，因此您可以尝试该方法。
- John Palmieri
3
Sage的“sphinx-build”在这种情况下无法工作，因为我的Cython文件是针对系统库而不是Sage的编译的。此外，我真的很想允许文档构建，即使用户没有Sage。 - Dan Stahlke
尝试查看Sage的conf.py（位于
sage/doc/common）是否有所帮助。 Sphinx的quickstart.py中也有一行：PROMPT_PREFIX = '> '。您可以尝试修改它并查看发生了什么。 - John Palmieri我认为魔法深深地隐藏在sage内部。
sage/doctest/parsing.py 中有一些内容，但是它们之间的联系并不清楚。有趣的是，在Sphinx中搜索 ['"]>>> ，只会出现 highlighting.py ，修改它并不能解决问题。也许doctest或pygments中的某些内容是相关的。 - Dan Stahlke1
我终于找到了如何预处理文档字符串的方法，将sage：更改为>>>。以下代码将放入我的项目的doc/conf.py文件中：
# Adapted from https://dev59.com/52bWa4cB1Zd3GeqPYqLn#11746519
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:”，这可能会误导读者。
- Dan Stahlke
1
好的，这是另一个想法：尝试在缩进块前加上双冒号。例如，在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的修改。有关源代码块，请参见Sphinx文档。
然后您需要修改一个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:
- John Palmieri
3
谢谢。不过这样做会有一个副作用，就是这些doctest不会被运行，对吗？理想情况下，我希望在安装sage时能够运行
sage: doctest。此外，我试图避免使用monkey patch Sphinx。但如果找到了一个好的解决方案，也许可以向他们提交一个补丁。 - Dan Stahlke如果你执行
sage -t 文件，Sage会运行那些doctest。这是所有Sage doctest的格式。 - John Palmieri好的，那么双冒号并没有使doctest变得不可见吗？我会尽快测试一下，只要我能让它在sage中运行（目前它给了我一个“numpy.ufunc大小错误，请尝试重新编译”的提示，我无法弄清楚为什么；sage是编译cython的）。 - Dan Stahlke
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接
sphinx-quickstart，它会设置一个conf.py和一个Makefile，这样你就可以执行make clean && make html。它会询问一些问题，最好告诉它使用一个doc目录，否则会污染你的项目目录。如果你想直接尝试我的项目，它在GitHub上的名称是qitensor，我已经在下面的回答中提到的地方修改了conf.py。 - Dan Stahlke