← 返回首页
bpo-36675: Doc: Reveal doctest directives by JulienPalard · Pull Request #23620 · python/cpython · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

bpo-36675: Doc: Reveal doctest directives#23620

Merged
JulienPalard merged 2 commits into
python:masterfrom
JulienPalard:doctest
Dec 15, 2020
Merged

bpo-36675: Doc: Reveal doctest directives#23620
JulienPalard merged 2 commits into
python:masterfrom
JulienPalard:doctest

Conversation

JulienPalard commented Dec 2, 2020 •
edited by bedevere-bot
Loading

Copy link
Copy Markdown
Member

Doctest directive were hidden in HTML and PDF output, this PR show them back.

https://bugs.python.org/issue36675

bedevere-bot added docs Documentation in the Doc dir awaiting core review labels Dec 2, 2020

JulienPalard commented Dec 2, 2020

Copy link
Copy Markdown
Member Author

Backport won't be possible, we have older sphinx on older branches.

JulienPalard commented Dec 3, 2020

Copy link
Copy Markdown
Member Author

@andresdelfino I see you a lot on the doc those time, though you would be interested in proofreading this :)

andresdelfino commented Dec 3, 2020

Copy link
Copy Markdown
Contributor

@JulienPalard Sure!

JulienPalard merged commit c8a10d2 into python:master Dec 15, 2020

andresdelfino commented Dec 15, 2020

Copy link
Copy Markdown
Contributor

@JulienPalard could you check the comment I made? I believe something is missing.

JulienPalard commented Dec 16, 2020

Copy link
Copy Markdown
Member Author

@andresdelfino Gladly, but, which comment?

andresdelfino reviewed Dec 16, 2020
View reviewed changes
Comment thread Doc/library/doctest.rst
Another bad idea is to print things that embed an object address, like

.. doctest::

andresdelfino Dec 3, 2020

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Perhaps

Suggested change
:no-trim-doctest-flags:

is missing here?

andresdelfino Dec 3, 2020

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

The rendered docs doesn't show the doctest directive in this case.

JulienPalard Dec 17, 2020

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

I think it's better to keep it hidden in this case. The case is:

>>> id(1.0) # certain to fail some of the time 7948648 >>> class C: pass >>> C() # the default repr() for instances embeds an address <C object at 0x00AC18F0>

the comment in the case is true: it's expected to fail. If we reveal the hidden doctest: +SKIP it's no longer expected to fail, the comment becomes erroneous.

The point of this example is to demo usefull cases for +ELLIPSIS, not +SKIP.

andresdelfino Dec 17, 2020

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Oh, ok :)

andresdelfino commented Dec 16, 2020

Copy link
Copy Markdown
Contributor

@JulienPalard sorry, I thought it was submitted, but I was seeing a draft.

asottile commented Jan 5, 2021

Copy link
Copy Markdown
Contributor

This breaks the minimum version of sphinx listed in Docs/conf.py:

cpython/Doc/conf.py

Line 48 in f7f0ed5

needs_sphinx = '1.8'

:no-trim-doctest-flags: was added in sphinx 3.2 whereas the minimum version in Docs/conf.py is 1.8: sphinx-doc/sphinx@784e763

JulienPalard commented Jan 6, 2021

Copy link
Copy Markdown
Member Author

@asottile that's right, let's bump this, thanks for noticing!

JulienPalard mentioned this pull request Jan 6, 2021
Closed

asottile commented Jan 6, 2021

Copy link
Copy Markdown
Contributor

@JulienPalard there's been additional efforts in this release to maintain compatibility with 1.x so there might be competing opinions here

JulienPalard commented Jan 6, 2021 •
edited
Loading

Copy link
Copy Markdown
Member Author

Ok so let's discuss this futher in an issue. I'm opening it → https://bugs.python.org/issue42843

asottile commented Jan 6, 2021

Copy link
Copy Markdown
Contributor

sounds good -- I only noticed this because it broke the packaging for deadsnakes (on 20.04, 18.04 and 16.04) so I reverted this patch there: deadsnakes/python3.10@f69292e

JulienPalard commented Jan 6, 2021

Copy link
Copy Markdown
Member Author

I only noticed this because it broke the packaging for deadsnakes

Sorry for this :(

asottile commented Jan 6, 2021

Copy link
Copy Markdown
Contributor

I only noticed this because it broke the packaging for deadsnakes

Sorry for this :(

no big deal, I'm considering dropping the documentation build since it's ~95% of my maintenance and I'm not sure anybody actually uses it.

JulienPalard added a commit to JulienPalard/cpython that referenced this pull request Jan 21, 2021
Revert "bpo-36675: Doc: Reveal doctest directives (pythonGH-23620)" …
882b942
This reverts commit c8a10d2.
adorilson pushed a commit to adorilson/cpython that referenced this pull request Mar 13, 2021
bpo-36675: Doc: Reveal doctest directives (pythonGH-23620)
fb38c64
JulienPalard deleted the doctest branch October 9, 2021 07:31
This was referenced May 5, 2022
Merged
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
andresdelfino andresdelfino left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

Footer

© 2026 GitHub, Inc.