Sphinx不删除html输出中的doctest标志 [英] Sphinx not removing doctest flags in html output

问题描述

我无法消除doctest标志（即< BLANKLINE> ，＃doctest：+ ELLIPSIS ） html输出。我能够生成所需的文档，因此没有错误，但其中包含我要删除的这些标记。 Sphinx文档

解决方案

根据@mzjn的评论，看来这是一个漏洞，已在Sphinx 2.2.0中修复：

问题： doctest自Sphinx 1.8.0以来没有被删节-问题＃6545

I cannot eliminate the doctest flags (ie. <BLANKLINE>, # doctest: +ELLIPSIS) for the html output. I am able to generate the documentation as I would like, so no errors there but it includes theses flags which I would like removed. Sphinx documentation here claims this is possible so I must be doing something wrong. My documentation examples are in numpy style and I have tried using both the napoleon and numpydoc extensions.

Here are the steps I have taken.

1. run sphinx-quickstart (enabling autodoc and doctest extensions)
2. run sphinx-apidoc to generate .rst files
3. run make doctest (all tests are passing)
4. run make html

I have tried the setting trim_doctest_flags and doctest_test_doctest_blocks variables in conf.py with no success.

Is there something I am missing to trigger sphinx to remove these for the html docs? I am hoping this is enough information to get pointed in the right direction since the docs look good except for this one issue. However, I can provide more details or an example if necessary.

Update: MCV Example (Using Sphinx 1.8.2)
directory and file structure

.
├── 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 - this was generated using 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')

using make html or sphinx-build -b html source build
trial.html output:

解决方案

Based on the comment by @mzjn, it appears that this was a bug, fixed in Sphinx 2.2.0:

Issue: doctest comments not getting trimmed since Sphinx 1.8.0 - Issue #6545

这篇关于Sphinx不删除html输出中的doctest标志的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！