Skip to content

gh-80856: doc: reveal doctest directives - #92318

Merged
ezio-melotti merged 2 commits into
python:mainfrom
sorcio:doctest-reveal
May 8, 2022
Merged

gh-80856: doc: reveal doctest directives#92318
ezio-melotti merged 2 commits into
python:mainfrom
sorcio:doctest-reveal

Conversation

@sorcio

@sorciosorcio commented May 5, 2022•
edited
Loading

Copy link
Copy Markdown
Contributor

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

ghost commented May 5, 2022•
edited by ghost
Loading

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.
CLA signed

@bedevere-botbedevere-bot added docs Documentation in the Doc dir awaiting review labels May 5, 2022
@sorciosorcio mentioned this pull request May 5, 2022
Closed
ezio-melotti
ezio-melotti approved these changes May 5, 2022
View reviewed changes

@ezio-melottiezio-melotti left a comment

Copy link
Copy Markdown
Member

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.

Comment threadDoc/library/doctest.rst Outdated
Comment threadDoc/library/doctest.rst Outdated
@ezio-melottiezio-melotti self-assigned this May 6, 2022
@ezio-melotti
ezio-melotti merged commit 7b024e3 into python:mainMay 8, 2022
@miss-islington

miss-islington commented May 8, 2022

Copy link
Copy Markdown
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
@sorcio@miss-islington
pythongh-80856: doc: reveal doctest directives (pythonGH-92318)
88c2339
* 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

bedevere-bot commented May 8, 2022

Copy link
Copy Markdown

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

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

bedevere-bot commented May 8, 2022

Copy link
Copy Markdown

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
@sorcio@miss-islington
pythongh-80856: doc: reveal doctest directives (pythonGH-92318)
f0e46b8
* 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
@miss-islington@sorcio
gh-80856: doc: reveal doctest directives (GH-92318)
1dbf699
* 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
@miss-islington@sorcio
gh-80856: doc: reveal doctest directives (GH-92318)
d6b83a3
* 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

JulienPalard commented May 8, 2022

Copy link
Copy Markdown
Member

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

sorcio commented May 8, 2022

Copy link
Copy Markdown
ContributorAuthor

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

asottile commented May 9, 2022

Copy link
Copy Markdown
Contributor

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

This was referenced May 9, 2022
Closed
Merged
@sorciosorcio mentioned this pull request May 29, 2022
Merged
@hugovkhugovk mentioned this pull request Jun 12, 2022
Merged
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ezio-melottiezio-melottiezio-melotti approved these changes
@JulienPalardJulienPalardAwaiting requested review from JulienPalard

Assignees

@ezio-melottiezio-melotti

Labels

docsDocumentation in the Doc dirskip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@sorcio@miss-islington@bedevere-bot@JulienPalard@asottile@ezio-melotti@JelleZijlstra@AlexWaygood