sphinx-doc / sphinx-doc/sphinx

Trailing white space stripped from doctests

Open
#9,849 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:doctest type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

This doctest fails, and I don't think it should:

>>> text = '''foo
... bar 
...  baz
... ba t
... '''
>>> print(repr(text))
'foo\nbar \n baz\nba t\n'
>>> text.count(' ')
3

The reason it fails, is there is a trailing space after "bar" (on line 2), but this is eliminated before the source is passed to doctest, thus text is assigned the value foo\nbar\n baz\nba t\n instead of foo\nbar \n baz\nba t\n. Whilst I generally really hate trailing white space, if the space matters... then it matters... So report is:

**********************************************************************
File "index.rst", line 9, in default
Failed example:
    print(repr(text))
Expected:
    'foo\nbar \n baz\nba t\n'
Got:
    'foo\nbar\n baz\nba t\n'
**********************************************************************
File "index.rst", line 11, in default
Failed example:
    text.count(' ')
Expected:
    3
Got:
    2
**********************************************************************

Invoking doctest on the rst directly the test above passes no problem.

How to Reproduce
$ mkdir foobar
$ cd foobar
$ python3 -m venv venv
$ . venv/bin/activate
$ pip install sphinx
$ sphinx-quickstart --sep --project foobar --author 'Does Not Matter' --release 0.0.1 --language en --ext-doctest
$ cat > source/index.rst 
foobar
======

.. doctest::

   >>> text = '''foo
   ... bar 
   ...  baz
   ... ba t
   ... '''
   >>> print(repr(text))
   'foo\nbar \n baz\nba t\n'
   >>> text.count(' ')
   3
^D
$ make doctest
Expected behavior

Doc test illustrated above passes.

Your project

N/A

Screenshots

No response

OS

Linux

Python version

3.8.10

Sphinx version

4.3.0

Sphinx extensions

No response

Extra tools

No response

Additional context

I had a little look into it and I can see the source is serialised with pickle in build/doctrees (in this above case), with the space missing. Or at least getting it back out the space is missing by that point anyway.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the failure with the provided Sphinx project and make doctest, then inspect the doctest source as it is serialized in build/doctrees. Trace where the trailing space disappears before execution; done means the example preserves it and passes with the expected count and representation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, testing-qa
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.