gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` #124106

hugovk · 2024-09-15T16:25:25Z

Fix 26 warnings in library/unittest.mock.rst:

Before:

❯ make -C Doc html SPHINXOPTS="-n -W --keep-going" SOURCES="library/unittest.mock.rst" 2>&1 | grep WARNING | tee >(wc -l)
library/unittest.mock.rst:71: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:740: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:763: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:763: WARNING: py:attr reference target not found: spec_set [ref.attr]
library/unittest.mock.rst:1177: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1199: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1199: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1215: WARNING: py:attr reference target not found: mock.return_value [ref.attr]
library/unittest.mock.rst:1215: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1234: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1234: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1248: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:1287: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:1458: WARNING: py:class reference target not found: TestCase [ref.class]
library/unittest.mock.rst:1495: WARNING: py:attr reference target not found: return_value [ref.attr]
library/unittest.mock.rst:1818: WARNING: py:meth reference target not found: start [ref.meth]
library/unittest.mock.rst:1818: WARNING: py:meth reference target not found: stop [ref.meth]
library/unittest.mock.rst:1822: WARNING: py:meth reference target not found: start [ref.meth]
library/unittest.mock.rst:1822: WARNING: py:meth reference target not found: stop [ref.meth]
library/unittest.mock.rst:1840: WARNING: py:class reference target not found: TestCase [ref.class]
library/unittest.mock.rst:2204: WARNING: py:meth reference target not found: MagicMock.__iter__ [ref.meth]
library/unittest.mock.rst:2512: WARNING: py:const reference target not found: mock.FILTER_DIR [ref.const]
library/unittest.mock.rst:2529: WARNING: py:meth reference target not found: io.IOBase.read [ref.meth]
library/unittest.mock.rst:2540: WARNING: py:meth reference target not found: io.IOBase.read [ref.meth]
library/unittest.mock.rst:2593: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:2618: WARNING: py:mod reference target not found: mock [ref.mod]
library/unittest.mock.rst:2618: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:2657: WARNING: py:class reference target not found: request.Request [ref.class]
library/unittest.mock.rst:2657: WARNING: py:class reference target not found: request.Request [ref.class]
library/unittest.mock.rst:2673: WARNING: py:class reference target not found: Request [ref.class]
library/unittest.mock.rst:2673: WARNING: py:class reference target not found: request.Request [ref.class]
library/unittest.mock.rst:2826: WARNING: py:attr reference target not found: side_effect [ref.attr]
library/unittest.mock.rst:2826: WARNING: py:attr reference target not found: return_value [ref.attr]
      33

After:

❯ make -C Doc html SPHINXOPTS="-n -W --keep-going" SOURCES="library/unittest.mock.rst" 2>&1 | grep WARNING | tee >(wc -l)
library/unittest.mock.rst:740: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:763: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:763: WARNING: py:attr reference target not found: spec_set [ref.attr]
library/unittest.mock.rst:1287: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:2204: WARNING: py:meth reference target not found: MagicMock.__iter__ [ref.meth]
library/unittest.mock.rst:2593: WARNING: py:attr reference target not found: spec [ref.attr]
library/unittest.mock.rst:2618: WARNING: py:attr reference target not found: spec [ref.attr]
       7

Issue: Fix all Sphinx reference warnings in the documentation #101100

📚 Documentation preview 📚: https://cpython-previews--124106.org.readthedocs.build/

picnixz · 2024-09-16T09:09:57Z

Doc/library/unittest.mock.rst

-        Normally the :attr:`__class__` attribute of an object will return its type.
-        For a mock object with a :attr:`spec`, ``__class__`` returns the spec class
+        Normally the :attr:`!__class__` attribute of an object will return its type.
+        For a mock object with a :attr:`spec`, :attr:`!__class__` returns the spec class


The spec attribute seems to be missing or is it an inherited one? (Maybe we could fix it in this PR directly?). Or is it a Sphinx issue?

I think it (and spec_set) are just missing documentation under https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock

For example, here's side_effect:

https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock.side_effect

Would you like to suggest some text?

I never used it so I cannot really suggest a good text. I'll leave that task to unittest experts! but we can do it in another PR otherwise.

vstinner · 2024-09-16T22:37:26Z

Doc/library/unittest.mock.rst

@@ -2615,7 +2615,7 @@ unit tests. Testing everything in isolation is all fine and dandy, but if you
 don't test how your units are "wired together" there is still lots of room
 for bugs that tests might have caught.

-:mod:`mock` already provides a feature to help with this, called speccing. If you
+:mod:`unittest.mock` already provides a feature to help with this, called speccing. If you
 use a class or instance as the :attr:`spec` for a mock then you can only access


There is a warning on "spec" here.

Yep, it's not yet documented, can you suggest some text for it? Also for spec_set?

Maybe just write :attr:`!spec` .

Done, and also for spec_set.

miss-islington-app · 2024-10-09T14:02:21Z

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

…ythonGH-124106) (cherry picked from commit a5716a3) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

bedevere-app · 2024-10-09T14:02:39Z

GH-125190 is a backport of this pull request to the 3.13 branch.

bedevere-app · 2024-10-09T14:02:44Z

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

…H-124106) (#125190) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…H-124106) (#125191) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Fix Sphinx warnings in library/unittest.mock.rst

f77e1a6

hugovk added docs Documentation in the Doc dir skip news labels Sep 15, 2024

bedevere-app bot added the awaiting core review label Sep 15, 2024

bedevere-app bot mentioned this pull request Sep 15, 2024

Fix all Sphinx reference warnings in the documentation #101100

Open

picnixz reviewed Sep 16, 2024

View reviewed changes

hugovk added needs backport to 3.12 bug and security fixes needs backport to 3.13 bugs and security fixes labels Sep 16, 2024

vstinner reviewed Sep 16, 2024

View reviewed changes

Silence Sphinx warnings for spec and spec_set

5e8e6b8

hugovk merged commit a5716a3 into python:main Oct 9, 2024
23 checks passed

hugovk deleted the docs-fix-sphinx-warnings-unittest.mock branch October 9, 2024 14:02

bedevere-app bot removed the awaiting core review label Oct 9, 2024

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Oct 9, 2024

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

hugovk added a commit that referenced this pull request Oct 9, 2024

[3.13] gh-101100: Fix Sphinx warnings in library/unittest.mock.rst (G…

ab5f179

…H-124106) (#125190) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

hugovk added a commit that referenced this pull request Oct 9, 2024

[3.12] gh-101100: Fix Sphinx warnings in library/unittest.mock.rst (G…

7187d4f

…H-124106) (#125191) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` #124106

gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` #124106

hugovk commented Sep 15, 2024 •

edited by github-actions bot

Loading

picnixz Sep 16, 2024 •

edited

Loading

hugovk Sep 16, 2024

picnixz Sep 16, 2024

vstinner Sep 16, 2024

hugovk Sep 17, 2024

vstinner Sep 17, 2024

hugovk Sep 23, 2024

miss-islington-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

gh-101100: Fix Sphinx warnings in library/unittest.mock.rst #124106

gh-101100: Fix Sphinx warnings in library/unittest.mock.rst #124106

Conversation

hugovk commented Sep 15, 2024 • edited by github-actions bot Loading

picnixz Sep 16, 2024 • edited Loading

Choose a reason for hiding this comment

hugovk Sep 16, 2024

Choose a reason for hiding this comment

picnixz Sep 16, 2024

Choose a reason for hiding this comment

vstinner Sep 16, 2024

Choose a reason for hiding this comment

hugovk Sep 17, 2024

Choose a reason for hiding this comment

vstinner Sep 17, 2024

Choose a reason for hiding this comment

hugovk Sep 23, 2024

Choose a reason for hiding this comment

miss-islington-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` #124106

gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` #124106

hugovk commented Sep 15, 2024 •

edited by github-actions bot

Loading

picnixz Sep 16, 2024 •

edited

Loading