Sphinx 未删除 html 输出中的 doctest 标志答案

【问题标题】：Sphinx not removing doctest flags in html outputSphinx 未删除 html 输出中的 doctest 标志
【发布时间】：2019-03-07 21:11:58
【问题描述】：

我无法消除 html 输出的 doctest 标志（即<BLANKLINE>、# doctest: +ELLIPSIS）。我能够根据需要生成文档，因此没有错误，但它包含我想删除的这些标志。 Sphinx 文档here 声称这是可能的，所以我一定做错了什么。我的文档示例采用 numpy 风格，我尝试过使用 napoleon 和 numpydoc 扩展。

这是我采取的步骤。

运行sphinx-quickstart（启用autodoc 和doctest 扩展）
运行sphinx-apidoc生成.rst文件
运行make doctest（所有测试均通过）
运行make html

我已尝试在conf.py 中设置trim_doctest_flags 和doctest_test_doctest_blocks 变量，但没有成功。

我是否缺少某些东西来触发 sphinx 为 html 文档删除这些内容？我希望这是足够的信息来指出正确的方向，因为除了这个问题之外，文档看起来不错。但是，如果需要，我可以提供更多详细信息或示例。

更新：MCV 示例（使用 Sphinx 1.8.2）
目录和文件结构

.
├── trial
│   ├── __init__.py
│   └── trial.py
└── trialDocs
    ├── build
    ├── Makefile
    └── source
        ├── _static
        ├── _templates
        ├── conf.py
        ├── index.rst
        ├── modules.rst
        └── trial.rst

conf.py

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
import os
import sys
sys.path.insert(0, os.path.abspath('../../trial'))
project = 'trial'
copyright = '2019, trial'
author = 'trial'
version = ''
release = 'trial'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.napoleon',
]
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
language = None
exclude_patterns = []
pygments_style = None
html_theme = 'alabaster'
htmlhelp_basename = 'trialdoc'
latex_elements = {}
latex_documents = [(master_doc, 'trial.tex', 'trial Documentation', 'trial', 'manual'),]
man_pages = [(master_doc, 'trial', 'trial Documentation', [author], 1)]
texinfo_documents = [(master_doc, 'trial', 'trial Documentation', author, 'trial', 'One line description of project.', 'Miscellaneous'),]
epub_title = project
epub_exclude_files = ['search.html']
doctest_global_setup = """
from trial import *
"""
trim_doctest_flags=True

trial.rst - 这是使用 sphinx-apidoc 生成的

trial package
=============

Module contents
---------------

.. automodule:: trial
    :members:
    :undoc-members:
    :show-inheritance:

试用.py

def withBlankline():
    """
    Use blanklines in example.

    Determine if sphinx will eliminate <BLANKLINE> for html.

    Examples
    --------
    >>> withBlankline()
    <BLANKLINE>
    blanklines above and below
    <BLANKLINE>
    """
    print()
    print('blanklines above and below')
    print()

class Example():
    def __init__(self):
        pass

    def withEllipsis(self):
        """
        Use ellipsis in example.

        Determine if sphinx will eliminate # doctest: +ELLIPSIS for html.

        Examples
        --------
        >>> e = Example()
        >>> e.withEllipsis() # doctest: +ELLIPSIS
        abc...xyz
        """
        print('abcdefghijklmnopqrstuvwxyz')

使用make html 或sphinx-build -b html source build
trial.html 输出：

【问题讨论】：

是的，我认为您需要提供更多详细信息。我们如何重现这个？
@mzjn 没问题，我已经更新了我的问题。如果您需要其他任何东西来重现，请告诉我。谢谢。
有趣。我可以重现这个问题。 trim_doctest_flags 默认为 True，应该注意这一点。
嗯。我想我现在可以编写一个脚本来手动修复它。
在 Sphinx 2.2.0 中修复：github.com/sphinx-doc/sphinx/issues/6545

标签： python python-sphinx doctest autodoc numpydoc

【解决方案1】：

根据@mzjn 的评论，这似乎是一个错误，已在 Sphinx 2.2.0 中修复：

问题：doctest comments not getting trimmed since Sphinx 1.8.0 - Issue #6545

【讨论】：