gh-80856: doc: reveal doctest directives

[sorcio]

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.

[ghost]

All commit authors signed the Contributor License Agreement.

[ezio-melotti]

There are a couple of whitespace inconsistencies, but otherwise LGTM.

[miss-islington]

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

[bedevere-bot]

GH-92493 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-92494 is a backport of this pull request to the 3.10 branch.

[JulienPalard]

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

cpython/Doc/conf.py

Line 48 in 859250c

needs_sphinx = '1.8'

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).

[sorcio]

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?

[asottile]

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! 👍