Sphinx 未删除 html 输出中的 doctest 标志
Sphinx not removing doctest flags in html output
我无法消除 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:
trial.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 的评论,这似乎是一个错误,已在 Sphinx 2.2.0 中修复:
问题:doctest comments not getting trimmed since Sphinx 1.8.0 - Issue #6545
我无法消除 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:
trial.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 的评论,这似乎是一个错误,已在 Sphinx 2.2.0 中修复:
问题:doctest comments not getting trimmed since Sphinx 1.8.0 - Issue #6545