Issue: gh-80856

This is literally just the change from #23620 cherry-picked to apply on top of main again.

Since docs now build on Sphinx 4.5.0, :no-trim-doctest-flags: is now supported and this change can be applied.

All commit authors signed the Contributor License Agreement.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @sorcio for the PR, and @ezio-melotti for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

* Doc: Reveal doctest directives.

* Fix whitespace.

Co-authored-by: Julien Palard <julien@palard.fr>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
(cherry picked from commit 7b024e3)

Co-authored-by: Davide Rizzo <sorcio@gmail.com>

Beware @sorcio, this "breaks" the minimum version of sphinx listed in Docs/conf.py:

The :no-trim-doctest-flags: was added in sphinx 3.2, so you need to bump to needs-sphinx = '3.2'.

Bumping needs-sphinx to 3.2 were not OK one year ago, but it may be OK now, I really don't know. Let's ask to @asottile @doko42.

The only thing I see is that one year ago Debian stable were shipping sphinx-doc==1.8 and now it ships sphinx-doc==3.4, this was the lone blocker as seen by @vstinner in #87009 (comment).

Hey @JulienPalard, thanks for the heads up! I'll wait for their responses and patch things up as needed. I hadn't noticed that you previously suggested compatibility with Sphinx 2 would be maintained for "a few more releases", otherwise I wouldn't have pushed this forward.

If the limitation to stay with Sphinx < 3 is confirmed, would it apply to 3.10 only or to main as well? This has been a bug in the published doc for a while. In the worst case, I'd consider adding a backport of the doctest directive.

I think the questions are:

1. Can 3.10 use Sphinx 3.2+ features? (If yes, needs_sphinx has to be bumped)
2. Can main? (If yes, needs_sphinx has to be bumped)
3. If the answer to both is no, would it be acceptable to add a directive (maybe in pyspecific.py) to cover this case for older Sphinx?

I can't speak for debian but I've disabled the docs builds entirely for the pythons I distribute for deadsnakes (it ended up being 90%+ of the maintenance work so I stopped trying) so bumping the version there is no longer a concern for me! 👍