Sphinx not removing doctest flags in html output

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.

run sphinx-quickstart (enabling autodoc and doctest extensions)
run sphinx-apidoc to generate .rst files
run make doctest (all tests are passing)
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')

Answer

It seems you're having trouble removing the doctest flags (<BLANKLINE>, # doctest: +ELLIPSIS) from the HTML output in Sphinx documentation. You've already tried some of the suggested configurations like trim_doctest_flags and doctest_test_doctest_blocks, but they didn't seem to resolve the issue.

Here’s a breakdown of the steps and some additional suggestions to help you fix this:

1. Ensure `trim_doctest_flags` is set correctly

The trim_doctest_flags setting in conf.py should be enabled to remove # doctest: +ELLIPSIS and similar flags from your HTML output. You have this in your configuration, but let’s make sure it is set correctly and try modifying it a little bit to ensure it works.

Make sure trim_doctest_flags is set like this:

trim_doctest_flags = True

This should remove flags like # doctest: +ELLIPSIS from your HTML output.

2. Ensure You Are Using `doctest_test_doctest_blocks` Correctly

The doctest_test_doctest_blocks setting controls whether to strip the # doctest flags in doctest blocks.

In your case, you need to ensure that both trim_doctest_flags and doctest_test_doctest_blocks are set correctly in conf.py:

doctest_test_doctest_blocks = True
trim_doctest_flags = True

By enabling both of these, it should strip the doctest-specific annotations from the HTML output.

3. Check the Sphinx Version

The settings you’re using are supposed to work with Sphinx version 1.8.2. However, there might be minor issues with versions or bugs that could cause unexpected behavior. If possible, try upgrading Sphinx to the latest version (e.g., Sphinx 4.x or 5.x), as newer versions may have fixed some issues related to doctests and HTML formatting:

pip install --upgrade sphinx

Then, re-run the make html command.

4. Adjusting `doctest_global_setup`

While doctest_global_setup is typically used for setting up the testing environment (such as importing the module for doctests), it should not affect how the doctests are rendered in the HTML output. You already have doctest_global_setup defined, so make sure it's properly included as:

doctest_global_setup = """
from trial import *
"""

Ensure that the doctest_global_setup setup doesn’t interfere with the rendering of the doctests by using proper imports.

5. Test Output in Different Formats

Sometimes the issue might be with the HTML rendering itself. Try rendering your documentation in a different format (e.g., LaTeX, PDF, or plain text) to see if the doctest flags still appear.

make latex

This can help isolate the issue to HTML output specifically.

6. Ensure Correct Formatting in `.rst` Files

In your .rst files, ensure that the doctest blocks are correctly formatted. For example:

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

7. Check for Interfering Extensions

You’re using both the napoleon and numpydoc extensions in Sphinx, which handle docstring formats. Sometimes, these can interfere with each other or with the rendering of doctests. To test this, try disabling the numpydoc extension temporarily and see if the issue persists.

Modify your extensions list to:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.napoleon',  # Disable numpydoc temporarily
]

Re-run the build and see if it resolves the issue.

8. Re-run the Build with Clean Output

Sometimes Sphinx might cache old results. Try cleaning the build directory before re-running make html:

make clean
make html

This will ensure no old output files are being reused.

Final Configuration Example:

Here’s a consolidated configuration for conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../../trial'))

# Project information
project = 'trial'
copyright = '2019, trial'
author = 'trial'
version = ''
release = 'trial'

# Extensions to use
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.napoleon',  # Optional: Remove numpydoc if not needed
]

# Templates and source files
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
language = None
exclude_patterns = []
pygments_style = None

# HTML output options
html_theme = 'alabaster'
htmlhelp_basename = 'trialdoc'

# LaTeX options (optional)
latex_elements = {}
latex_documents = [(master_doc, 'trial.tex', 'trial Documentation', 'trial', 'manual'),]

# Man pages
man_pages = [(master_doc, 'trial', 'trial Documentation', [author], 1)]

# Texinfo options
texinfo_documents = [(master_doc, 'trial', 'trial Documentation', author, 'trial', 'One line description of project.', 'Miscellaneous')]

# Doctest setup and flag removal
doctest_global_setup = """
from trial import *
"""
trim_doctest_flags = True
doctest_test_doctest_blocks = True

Conclusion:

By ensuring both trim_doctest_flags and doctest_test_doctest_blocks are correctly set and testing with different Sphinx versions, the doctest flags (<BLANKLINE>, # doctest: +ELLIPSIS) should be removed from your HTML output. Also, ensure that you test in a clean build directory to avoid issues with cached files.

Sphinx not removing doctest flags in html output

Answer

1. Ensure `trim_doctest_flags` is set correctly

2. Ensure You Are Using `doctest_test_doctest_blocks` Correctly

3. Check the Sphinx Version

4. Adjusting `doctest_global_setup`

5. Test Output in Different Formats

6. Ensure Correct Formatting in `.rst` Files

7. Check for Interfering Extensions

8. Re-run the Build with Clean Output

Final Configuration Example:

Conclusion:

Hot

Latest

Sphinx not removing doctest flags in html output

Answer

1. Ensure trim_doctest_flags is set correctly

2. Ensure You Are Using doctest_test_doctest_blocks Correctly

3. Check the Sphinx Version

4. Adjusting doctest_global_setup

5. Test Output in Different Formats

6. Ensure Correct Formatting in .rst Files

7. Check for Interfering Extensions

8. Re-run the Build with Clean Output

Final Configuration Example:

Conclusion:

Hot

Latest

1. Ensure `trim_doctest_flags` is set correctly

2. Ensure You Are Using `doctest_test_doctest_blocks` Correctly

4. Adjusting `doctest_global_setup`

6. Ensure Correct Formatting in `.rst` Files