Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-80856: doc: reveal doctest directives #92318

Merged
merged 2 commits into from
May 8, 2022

Conversation

sorcio
Copy link
Contributor

@sorcio sorcio commented May 5, 2022

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.

@cpython-cla-bot
Copy link

cpython-cla-bot bot commented May 5, 2022

All commit authors signed the Contributor License Agreement.
CLA signed

Copy link
Member

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

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

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

Doc/library/doctest.rst Outdated Show resolved Hide resolved
Doc/library/doctest.rst Outdated Show resolved Hide resolved
@ezio-melotti ezio-melotti reopened this May 7, 2022
@JulienPalard JulienPalard reopened this May 7, 2022
@JelleZijlstra JelleZijlstra added needs backport to 3.9 only security fixes needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels May 8, 2022
@ezio-melotti ezio-melotti removed the needs backport to 3.9 only security fixes label May 8, 2022
@ezio-melotti ezio-melotti merged commit 7b024e3 into python:main May 8, 2022
@miss-islington
Copy link
Contributor

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 8, 2022
* 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>
@bedevere-bot
Copy link

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

@bedevere-bot bedevere-bot removed needs backport to 3.11 only security fixes needs backport to 3.10 only security fixes labels May 8, 2022
@bedevere-bot
Copy link

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 8, 2022
* 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>
miss-islington added a commit that referenced this pull request May 8, 2022
* 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>
miss-islington added a commit that referenced this pull request May 8, 2022
* 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>
@JulienPalard
Copy link
Member

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

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
Copy link
Contributor Author

sorcio commented May 8, 2022

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
Copy link
Contributor

asottile commented May 9, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

8 participants