gh-109510: Clearly explain "Which Docstrings Are Examined" #109696

Unique-Usman · 2023-09-21T21:27:16Z

The "Which Docstrings Are Examined" part of
Doctest documentation is ambiguos, This change explained it cleary with an example.

📚 Documentation preview 📚: https://cpython-previews--109696.org.readthedocs.build/en/109696/library/doctest.html#which-docstrings-are-examined

Issue: Doctest - No clear guidance on how to use the "Option Flag" and and the explanation of "Which Docstrings Are Examined" is ambiguos. #109510

The "Which Docstrings Are Examined" part of Doctest documentation is ambiguos, This change explained it cleary with an example.

cpython-cla-bot · 2023-09-21T21:27:18Z

All commit authors signed the Contributor License Agreement.

Doc/library/doctest.rst

Co-authored-by: Mariatta <Mariatta@users.noreply.github.com>

zware · 2023-10-04T18:11:29Z

@python/proofreaders, could we take a look here?

bskinn · 2023-10-05T20:35:04Z

Can you clarify your proofreading ask here, @zware?

If I read the thread right, the new content is not done yet, and the advice being sought is w.r.t. what to include, not how to write/format it.

zware · 2023-10-05T21:03:47Z

Sorry, could have clarified :). I meant to request proofreaders as a reviewer, but GitHub didn't give me the option to do so.

I recommended to @Unique-Usman to leave the further improvements to another PR rather than holding this one up. As such, I've marked the messages about further changes as 'off-topic'.

Unique-Usman · 2023-10-06T04:10:41Z

thank @zware as you recommended, I will be creating a new PR for the further improvement.

Doc/library/doctest.rst

JacobCoffee · 2023-10-11T20:14:23Z

Doc/library/doctest.rst

+The value of ``example.__test__["numbers"]`` value will be treated as
+docstring and all the tests inside it will be run. It is also
+important to note that the value can also be mapped to a Function,
+class object or module. If the value is a class, Function or module, doctest


Suggested change

class object or module. If the value is a class, Function or module, doctest

class object or module. If the value is a class, Function or module, :mod:`doctest`

Do we link?

Good question. We use the appropriate role to get the appropriate formatting, but add ! to not resolve the link, since it is to the current module docs that the reader is already on, which isn't particularly helpful.

Co-authored-by: Jacob Coffee <jacob@z7x.org>

Changed doctest :mod: `doctest`

Doc/library/doctest.rst

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

CAM-Gerlach

Hey, thanks for this. Looks good overall; I had some relatively modest feedback, all as suggestions you can apply. You can easily do so all in one go by going to Files, clicking Add to batch on each suggestion, and once done clicking Commit. Thanks!

Doc/library/doctest.rst

Accepted suggestions to meet python documentation convention Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Unique-Usman · 2023-10-12T03:22:00Z

@CAM-Gerlach Thanks for this it really helped.

CAM-Gerlach

LGTM overall, but I do have one last semi-substantive thing I'm confused on, which my previous changes ended up highlighting. Thanks!

Doc/library/doctest.rst

Changed :samp:`{name of M}.__test__.K` to ``M.__test__.K`` as the M is already a placeholder for name of the module. Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Doc/library/doctest.rst

bedevere-app · 2023-10-18T05:47:29Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Changed the `True` to "is true" to specify that ``M.__test__`` has a truthy value, rather than literally being True.

Unique-Usman · 2023-10-18T07:39:41Z

I have made the requested changes; please review again

Doc/library/doctest.rst

Changes "is true" to "is truthy" to imply that the value of ``M.__test__" has true value. Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

hugovk

Thank you!

miss-islington-app · 2023-10-19T15:10:10Z

Thanks @Unique-Usman for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

…honGH-109696) (cherry picked from commit bcc941b) Co-authored-by: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Co-authored-by: Mariatta <Mariatta@users.noreply.github.com> Co-authored-by: Jacob Coffee <jacob@z7x.org> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

bedevere-app · 2023-10-19T15:10:25Z

GH-111077 is a backport of this pull request to the 3.12 branch.

bedevere-app · 2023-10-19T15:10:30Z

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

…-109696) (#111077) Co-authored-by: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Co-authored-by: Mariatta <Mariatta@users.noreply.github.com> Co-authored-by: Jacob Coffee <jacob@z7x.org> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

…-109696) (#111078) Co-authored-by: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Co-authored-by: Mariatta <Mariatta@users.noreply.github.com> Co-authored-by: Jacob Coffee <jacob@z7x.org> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

…hon#109696) Co-authored-by: Mariatta <Mariatta@users.noreply.github.com> Co-authored-by: Jacob Coffee <jacob@z7x.org> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Clearly explained "Which Docstrings Are Examined"

df550a1

The "Which Docstrings Are Examined" part of Doctest documentation is ambiguos, This change explained it cleary with an example.

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Sep 21, 2023

AlexWaygood changed the title ~~#109510: Clearly explained "Which Docstrings Are Examined"~~ gh-109510: Clearly explained "Which Docstrings Are Examined" Sep 21, 2023

bedevere-app bot mentioned this pull request Sep 21, 2023

Doctest - No clear guidance on how to use the "Option Flag" and and the explanation of "Which Docstrings Are Examined" is ambiguos. #109510

Closed

Unique-Usman added 2 commits September 22, 2023 12:06

Correct few grammatical error

ae033f3

Correct few grammatical error

24483b8

Mariatta reviewed Sep 28, 2023

View reviewed changes

Doc/library/doctest.rst Outdated Show resolved Hide resolved

Update Doc/library/doctest.rst

3dd6b79

Co-authored-by: Mariatta <Mariatta@users.noreply.github.com>

This comment was marked as off-topic.

Sign in to view

JacobCoffee reviewed Oct 11, 2023

View reviewed changes

Unique-Usman and others added 3 commits October 12, 2023 01:47

Update Doc/library/doctest.rst

50d1bb4

Co-authored-by: Jacob Coffee <jacob@z7x.org>

Update Doc/library/doctest.rst

b0fa4fd

Co-authored-by: Jacob Coffee <jacob@z7x.org>

Update doctest.rst

92da923

Changed doctest :mod: `doctest`

hugovk reviewed Oct 11, 2023

View reviewed changes

Doc/library/doctest.rst Outdated Show resolved Hide resolved

Doc/library/doctest.rst Outdated Show resolved Hide resolved

Doc/library/doctest.rst Outdated Show resolved Hide resolved

Unique-Usman and others added 3 commits October 12, 2023 02:49

Update Doc/library/doctest.rst

f59961c

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Update Doc/library/doctest.rst

b45acd9

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Update Doc/library/doctest.rst

d67276d

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

CAM-Gerlach changed the title ~~gh-109510: Clearly explained "Which Docstrings Are Examined"~~ gh-109510: Clearly explain "Which Docstrings Are Examined" Oct 11, 2023

CAM-Gerlach reviewed Oct 11, 2023

View reviewed changes

Apply suggestions from code review

23d3b50

Accepted suggestions to meet python documentation convention Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

CAM-Gerlach approved these changes Oct 18, 2023

View reviewed changes

Doc/library/doctest.rst Outdated Show resolved Hide resolved

CAM-Gerlach requested a review from Mariatta October 18, 2023 00:41

Unique-Usman and others added 2 commits October 18, 2023 10:43

Update Doc/library/doctest.rst

0cbac0f

Changed :samp:`{name of M}.__test__.K` to ``M.__test__.K`` as the M is already a placeholder for name of the module. Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Merge branch 'main' into unique

6857842

hugovk requested changes Oct 18, 2023

View reviewed changes

Doc/library/doctest.rst Outdated Show resolved Hide resolved

bedevere-app bot added awaiting changes and removed awaiting merge labels Oct 18, 2023

Update doctest.rst

728717e

Changed the `True` to "is true" to specify that ``M.__test__`` has a truthy value, rather than literally being True.

hugovk reviewed Oct 18, 2023

View reviewed changes

Doc/library/doctest.rst Outdated Show resolved Hide resolved

Unique-Usman requested a review from hugovk October 19, 2023 13:49

Update Doc/library/doctest.rst

cbb1434

Changes "is true" to "is truthy" to imply that the value of ``M.__test__" has true value. Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

hugovk approved these changes Oct 19, 2023

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting changes labels Oct 19, 2023

hugovk added needs backport to 3.11 only security fixes needs backport to 3.12 bug and security fixes labels Oct 19, 2023

hugovk merged commit bcc941b into python:main Oct 19, 2023
25 of 26 checks passed

bedevere-app bot removed the awaiting merge label Oct 19, 2023

bedevere-app bot removed the needs backport to 3.12 bug and security fixes label Oct 19, 2023

bedevere-app bot removed the needs backport to 3.11 only security fixes label Oct 19, 2023

Unique-Usman deleted the unique branch October 20, 2023 19:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-109510: Clearly explain "Which Docstrings Are Examined" #109696

gh-109510: Clearly explain "Which Docstrings Are Examined" #109696

Unique-Usman commented Sep 21, 2023 •

edited by hugovk

cpython-cla-bot bot commented Sep 21, 2023 •

edited

This comment was marked as off-topic.

This comment was marked as off-topic.

zware commented Oct 4, 2023

bskinn commented Oct 5, 2023

zware commented Oct 5, 2023

Unique-Usman commented Oct 6, 2023

JacobCoffee Oct 11, 2023

CAM-Gerlach Oct 11, 2023

CAM-Gerlach left a comment

Unique-Usman commented Oct 12, 2023

CAM-Gerlach left a comment

bedevere-app bot commented Oct 18, 2023

Unique-Usman commented Oct 18, 2023

hugovk left a comment

miss-islington-app bot commented Oct 19, 2023

bedevere-app bot commented Oct 19, 2023

bedevere-app bot commented Oct 19, 2023

	class object or module. If the value is a class, Function or module, doctest
	class object or module. If the value is a class, Function or module, :mod:`doctest`

gh-109510: Clearly explain "Which Docstrings Are Examined" #109696

gh-109510: Clearly explain "Which Docstrings Are Examined" #109696

Conversation

Unique-Usman commented Sep 21, 2023 • edited by hugovk

cpython-cla-bot bot commented Sep 21, 2023 • edited

This comment was marked as off-topic.

This comment was marked as off-topic.

zware commented Oct 4, 2023

bskinn commented Oct 5, 2023

zware commented Oct 5, 2023

Unique-Usman commented Oct 6, 2023

JacobCoffee Oct 11, 2023

Choose a reason for hiding this comment

CAM-Gerlach Oct 11, 2023

Choose a reason for hiding this comment

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Unique-Usman commented Oct 12, 2023

CAM-Gerlach left a comment

Choose a reason for hiding this comment

bedevere-app bot commented Oct 18, 2023

Unique-Usman commented Oct 18, 2023

hugovk left a comment

Choose a reason for hiding this comment

miss-islington-app bot commented Oct 19, 2023

bedevere-app bot commented Oct 19, 2023

bedevere-app bot commented Oct 19, 2023

Unique-Usman commented Sep 21, 2023 •

edited by hugovk

cpython-cla-bot bot commented Sep 21, 2023 •

edited