8000 gh-101100: Sphinx warnings: pick the low hanging fruits (GH-107386) · python/cpython@f2d07d3 · GitHub
[go: up one dir, main page]
Skip to content

Commit f2d07d3

Browse files
serhiy-storchakaserhiy-storchaka
authored
gh-101100: Sphinx warnings: pick the low hanging fruits (GH-107386)
1 parent 413ba89 commit f2d07d3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+125
-139
lines changed

‎Doc/c-api/bool.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ creation and deletion functions don't apply to booleans. The following macros
1111
are available, however.
1212

1313

14+
.. c:var:: PyTypeObject PyBool_Type
15+
16+
This instance of :c:type:`PyTypeObject` represents the Python boolean type; it
17+
is the same object as :class:`bool` in the Python layer.
18+
19+
1420
.. c:function:: int PyBool_Check(PyObject *o)
1521
1622
Return true if *o* is of type :c:data:`PyBool_Type`. This function always

‎Doc/faq/extending.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,13 @@ How do I extract C values from a Python object?
8181

8282
That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size`
8383
returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified
84-
index. Lists have similar functions, :c:func:`PyListSize` and
84+
index. Lists have similar functions, :c:func:`PyList_Size` and
8585
:c:func:`PyList_GetItem`.
8686

8787
For bytes, :c:func:`PyBytes_Size` returns its length and
8888
:c:func:`PyBytes_AsStringAndSize` provides a pointer to its value and its
8989
length. Note that Python bytes objects may contain null bytes so C's
90-
:c:func:`strlen` should not be used.
90+
:c:func:`!strlen` should not be used.
9191

9292
To test the type of an object, first make sure it isn't ``NULL``, and then use
9393
:c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.

‎Doc/howto/curses.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -527,7 +527,7 @@ If you're in doubt about the detailed behavior of the curses
527527
functions, consult the manual pages for your curses implementation,
528528
whether it's ncurses or a proprietary Unix vendor's. The manual pages
529529
will document any quirks, and provide complete lists of all the
530-
functions, attributes, and :const:`ACS_\*` characters available to
530+
functions, attributes, and :ref:`ACS_\* <curses-acs-codes>` characters available to
531531
you.
532532

533533
Because the curses API is so large, some functions aren't supported in

‎Doc/install/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -778,7 +778,7 @@ Notes:
778778

779779
(2)
780780
On Unix, if the :envvar:`HOME` environment variable is not defined, the user's
781-
home directory will be determined with the :func:`getpwuid` function from the
781+
home directory will be determined with the :func:`~pwd.getpwuid` function from the
782782
standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser`
783783
function used by Distutils.
784784

‎Doc/library/asyncio-extending.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ Task lifetime support
6969
=====================
7070

7171
A third party task implementation should call the following functions to keep a task
72-
visible by :func:`asyncio.get_tasks` and :func:`asyncio.current_task`:
72+
visible by :func:`asyncio.all_tasks` and :func:`asyncio.current_task`:
7373

7474
.. function:: _register_task(task)
7575

‎Doc/library/asyncio-future.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -276,4 +276,4 @@ the Future has a result::
276276
:func:`concurrent.futures.as_completed` functions.
277277

278278
- :meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument,
279-
but :func:`concurrent.futures.cancel` does not.
279+
but :meth:`concurrent.futures.Future.cancel` does not.

‎Doc/library/bz2.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,8 @@ The :mod:`bz2` module contains:
8787
compressed streams.
8888

8989
:class:`BZ2File` provides all of the members specified by the
90-
:class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
90+
:class:`io.BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach`
91+
and :meth:`~io.IOBase.truncate`.
9192
Iteration and the :keyword:`with` statement are supported.
9293

9394
:class:`BZ2File` also provides the following method:

‎Doc/library/code.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -163,12 +163,12 @@ interpreter objects as well as the following additions.
163163

164164
Push a line of source text to the interpreter. The line should not have a
165165
trailing newline; it may have internal newlines. The line is appended to a
166-
buffer and the interpreter's :meth:`runsource` method is called with the
166+
buffer and the interpreter's :meth:`~InteractiveInterpreter.runsource` method is called with the
167167
concatenated contents of the buffer as source. If this indicates that the
168168
command was executed or invalid, the buffer is reset; otherwise, the command is
169169
incomplete, and the buffer is left as it was after the line was appended. The
170170
return value is ``True`` if more input is required, ``False`` if the line was
171-
dealt with in some way (this is the same as :meth:`runsource`).
171+
dealt with in some way (this is the same as :meth:`!runsource`).
172172

173173

174174
.. method:: InteractiveConsole.resetbuffer()

‎Doc/library/concurrent.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
The :mod:`concurrent` package
2-
=============================
1+
The :mod:`!concurrent` package
2+
==============================
33

44
Currently, there is only one module in this package:
55

‎Doc/library/curses.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1648,6 +1648,8 @@ keys); also, the following keypad mappings are standard:
16481648
| :kbd:`Page Down` | KEY_NPAGE |
16491649
+------------------+-----------+
16501650

1651+
.. _curses-acs-codes:
1652+
16511653
The following table lists characters from the alternate character set. These are
16521654
inherited from the VT100 terminal, and will generally be available on software
16531655
emulations such as X terminals. When there is no graphic available, curses

‎Doc/library/email.charset.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ Import this class from the :mod:`email.charset` module.
150150
.. method:: __str__()
151151

152152
Returns *input_charset* as a string coerced to lower
153-
case. :meth:`__repr__` is an alias for :meth:`__str__`.
153+
case. :meth:`!__repr__` is an alias for :meth:`!__str__`.
154154

155155

156156
.. method:: __eq__(other)

‎Doc/library/email.encoders.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type message
2525
containing binary data.
2626

2727
The :mod:`email` package provides some convenient encoders in its
28-
:mod:`encoders` module. These encoders are actually used by the
28+
:mod:`~email.encoders` module. These encoders are actually used by the
2929
:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
3030
class constructors to provide default encodings. All encoder functions take
3131
exactly one argument, the message object to encode. They usually extract the

‎Doc/library/email.generator.rst

Lines changed: 2 additions & 2 deletions
< 10000 /tr>
Original file line numberDiff line numberDiff line change
@@ -274,9 +274,9 @@ in with information about the part.
274274
.. rubric:: Footnotes
275275

276276
.. [#] This statement assumes that you use the appropriate setting for
277-
``unixfrom``, and that there are no :mod:`policy` settings calling for
277+
``unixfrom``, and that there are no :mod:`email.policy` settings calling for
278278
automatic adjustments (for example,
279-
:attr:`~email.policy.Policy.refold_source` must be ``none``, which is
279+
:attr:`~email.policy.EmailPolicy.refold_source` must be ``none``, which is
280280
*not* the default). It is also not 100% true, since if the message
281281
does not conform to the RFC standards occasionally information about the
282282
exact original text is lost during parsing error recovery. It is a goal

‎Doc/library/email.message.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ message objects.
6767
with the base :class:`~email.message.Message` class *maxheaderlen* is
6868
accepted, but defaults to ``None``, which means that by default the line
6969
length is controlled by the
70-
:attr:`~email.policy.EmailPolicy.max_line_length` of the policy. The
70+
:attr:`~email.policy.Policy.max_line_length` of the policy. The
7171
*policy* argument may be used to override the default policy obtained
7272
from the message instance. This can be used to control some of the
7373
formatting produced by the method, since the specified *policy* will be
@@ -213,7 +213,7 @@ message objects.
213213
del msg['subject']
214214
msg['subject'] = 'Python roolz!'
215215

216-
If the :mod:`policy` defines certain headers to be unique (as the standard
216+
If the :mod:`policy <email.policy>` defines certain headers to be unique (as the standard
217217
policies do), this method may raise a :exc:`ValueError` when an attempt
218218
is made to assign a value to such a header when one already exists. This
219219
behavior is intentional for consistency's sake, but do not depend on it
@@ -378,7 +378,7 @@ message objects.
378378
deprecated.
379379

380380
Note that existing parameter values of headers may be accessed through
381-
the :attr:`~email.headerregistry.BaseHeader.params` attribute of the
381+
the :attr:`~email.headerregistry.ParameterizedMIMEHeader.params` attribute of the
382382
header value (for example, ``msg['Content-Type'].params['charset']``).
383383

384384
.. versionchanged:: 3.4 ``replace`` keyword was added.
@@ -691,7 +691,7 @@ message objects.
691691

692692
.. method:: clear_content()
693693

694-
Remove the payload and all of the :exc:`Content-` headers, leaving
694+
Remove the payload and all of the :mailheader:`!Content-` headers, leaving
695695
all other headers intact and in their original order.
696696

697697

‎Doc/library/email.parser.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@ returns the root object when you close the parser.
3939
Note that the parser can be extended in limited ways, and of course you can
4040
implement your own parser completely from scratch. All of the logic that
4141
connects the :mod:`email` package's bundled parser and the
42-
:class:`~email.message.EmailMessage` class is embodied in the :mod:`policy`
42+
:class:`~email.message.EmailMessage` class is embodied in the :class:`~email.policy.Policy`
4343
class, so a custom parser can create message object trees any way it finds
44-
necessary by implementing custom versions of the appropriate :mod:`policy`
44+
necessary by implementing custom versions of the appropriate :class:`!Policy`
4545
methods.
4646

4747

‎Doc/library/filecmp.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ The :class:`dircmp` class
100100
used to get various bits of information about the directory trees being
101101
compared.
102102

103-
Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
103+
Note that via :meth:`~object.__getattr__` hooks, all attributes are computed lazily,
104104
so there is no speed penalty if only those attributes which are lightweight
105105
to compute are used.
106106

‎Doc/library/fileinput.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ available for subclassing as well:
177177
The keyword-only parameter *encoding* and *errors* are added.
178178

179179
.. versionchanged:: 3.11
180-
The ``'rU'`` and ``'U'`` modes and the :meth:`__getitem__` method have
180+
The ``'rU'`` and ``'U'`` modes and the :meth:`!__getitem__` method have
181181
been removed.
182182

183183

‎Doc/library/graphlib.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@
115115
:meth:`TopologicalSorter.done` is less than the number that have been
116116
returned by :meth:`TopologicalSorter.get_ready`.
117117

118-
The :meth:`~TopologicalSorter.__bool__` method of this class defers to
118+
The :meth:`~object.__bool__` method of this class defers to
119119
this function, so instead of::
120120

121121
if ts.is_active():
@@ -204,7 +204,7 @@ The :mod:`graphlib` module defines the following exception classes:
204204
in the working graph. If multiple cycles exist, only one undefined choice among them will
205205
be reported and included in the exception.
206206

207-
The detected cycle can be accessed via the second element in the :attr:`~CycleError.args`
207+
The detected cycle can be accessed via the second element in the :attr:`~BaseException.args`
208208
attribute of the exception instance and consists in a list of nodes, such that each node is,
209209
in the graph, an immediate predecessor of the next node in the list. In the reported list,
210210
the first and the last node will be the same, to make it clear that it is cyclic.

‎Doc/library/gzip.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ The module defines the following items:
7070
.. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
7171

7272
Constructor for the :class:`GzipFile` class, which simulates most of the
73-
methods of a :term:`file object`, with the exception of the :meth:`truncate`
73+
methods of a :term:`file object`, with the exception of the :meth:`~io.IOBase.truncate`
7474
method. At least one of *fileobj* and *filename* must be given a non-trivial
7575
value.
7676

@@ -113,7 +113,7 @@ The module defines the following items:
113113

114114
:class:`GzipFile` supports the :class:`io.BufferedIOBase` interface,
115115
including iteration and the :keyword:`with` statement. Only the
116-
:meth:`truncate` method isn't implemented.
116+
:meth:`~io.IOBase.truncate` method isn't implemented.
117117

118118
:class:`GzipFile` also provides the following method and attribute:
119119

‎Doc/library/hashlib.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -244,7 +244,7 @@ by the SHAKE algorithm.
244244

245245
.. method:: shake.digest(length)
246246

247-
Return the digest of the data passed to the :meth:`update` method so far.
247+
Return the digest of the data passed to the :meth:`~hash.update` method so far.
248248
This is a bytes object of size *length* which may contain bytes in
249249
the whole range from 0 to 255.
250250

@@ -507,9 +507,9 @@ Simple hashing
507507

508508
To calculate hash of some data, you should first construct a hash object by
509509
calling the appropriate constructor function (:func:`blake2b` or
510-
:func:`blake2s`), then update it with the data by calling :meth:`update` on the
510+
:func:`blake2s`), then update it with the data by calling :meth:`~hash.update` on the
511511
object, and, finally, get the digest out of the object by calling
512-
:meth:`digest` (or :meth:`hexdigest` for hex-encoded string).
512+
:meth:`~hash.digest` (or :meth:`~hash.hexdigest` for hex-encoded string).
513513

514514
>>> from hashlib import blake2b
515515
>>> h = blake2b()

‎Doc/library/importlib.resources.abc.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,10 @@
145145

146146
An abstract base class for resource readers capable of serving
147147
the :meth:`importlib.resources.files` interface. Subclasses
148-
:class:`importlib.resources.abc.ResourceReader` and provides
149-
concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s
148+
:class:`ResourceReader` and provides
149+
concrete implementations of the :class:`!ResourceReader`'s
150150
abstract methods. Therefore, any loader supplying
151-
:class:`importlib.abc.TraversableResources` also supplies ResourceReader.
151+
:class:`!TraversableResources` also supplies :class:`!ResourceReader`.
152152

153153
Loaders that wish to support resource reading are expected to
154154
implement this interface.

‎Doc/library/json.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ Basic Usage
192192
dictionaries will be sorted by key.
193193

194194
To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
195-
:meth:`default` method to serialize additional types), specify it with the
195+
:meth:`~JSONEncoder.default` method to serialize additional types), specify it with the
196196
*cls* kwarg; otherwise :class:`JSONEncoder` is used.
197197

198198
.. versionchanged:: 3.6
@@ -422,7 +422,7 @@ Encoders and Decoders
422422
Added support for int- and float-derived Enum classes.
423423

424424
To extend this to recognize other objects, subclass and implement a
425-
:meth:`default` method with another method that returns a serializable object
425+
:meth:`~JSONEncoder.default` method with another method that returns a serializable object
426426
for ``o`` if possible, otherwise it should call the superclass implementation
427427
(to raise :exc:`TypeError`).
428428

@@ -483,7 +483,7 @@ Encoders and Decoders
483483
:exc:`TypeError`).
484484

485485
For example, to support arbitrary iterators, you could implement
486-
:meth:`default` like this::
486+
:meth:`~JSONEncoder.default` like this::
487487

488488
def default(self, o):
489489
try:

‎Doc/library/logging.rst

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -397,21 +397,21 @@ have specific values relative to the predefined levels. If you define a level
397397
with the same numeric value, it overwrites the predefined value; the predefined
398398
name is lost.
399399

400-
+--------------+---------------+
401-
| Level | Numeric value |
402-
+==============+===============+
403-
| ``CRITICAL`` | 50 |
404-
+--------------+---------------+
405-
| ``ERROR`` | 40 |
406-
+--------------+---------------+
407-
| ``WARNING`` | 30 |
408-
+--------------+---------------+
409-
| ``INFO`` | 20 |
410-
+--------------+---------------+
411-
| ``DEBUG`` | 10 |
412-
+--------------+---------------+
413-
| ``NOTSET`` | 0 |
414-
+--------------+---------------+
400+
+-----------------------+---------------+
401+
| Level | Numeric value |
402+
+=======================+===============+
403+
| .. py:data:: CRITICAL | 50 |
404+
+-----------------------+---------------+
405+
| .. py:data:: ERROR | 40 |
406+
+-----------------------+---------------+
407+
| .. py:data:: WARNING | 30 |
408+
+-----------------------+---------------+
409+
| .. py:data:: INFO | 20 |
410+
+-----------------------+---------------+
411+
| .. py:data:: DEBUG | 10 |
412+
+-----------------------+---------------+
413+
| .. py:data:: NOTSET | 0 |
414+
+-----------------------+---------------+
415415

416416

417417
.. _handler:

‎Doc/library/lzma.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,8 @@ Reading and writing compressed files
100100
*filters* arguments have the same meanings as for :class:`LZMACompressor`.
101101

102102
:class:`LZMAFile` supports all the members specified by
103-
:class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
103+
:class:`io.BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach`
104+
and :meth:`~io.IOBase.truncate`.
104105
Iteration and the :keyword:`with` statement are supported.
105106

106107
The following method is also provided:

‎Doc/library/msvcrt.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ File Operations
3838
Lock part of a file based on file descriptor *fd* from the C runtime. Raises
3939
:exc:`OSError` on failure. The locked region of the file extends from the
4040
current file position for *nbytes* bytes, and may continue beyond the end of the
41-
file. *mode* must be one of the :const:`LK_\*` constants listed below. Multiple
41+
file. *mode* must be one of the :const:`!LK_\*` constants listed below. Multiple
4242
regions in a file may be locked at the same time, but may not overlap. Adjacent
4343
regions are not merged; they must be unlocked individually.
4444

‎Doc/library/netrc.rst

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,19 @@ the Unix :program:`ftp` program and other FTP clients.
5151

5252
Exception raised by the :class:`~netrc.netrc` class when syntactical errors are
5353
encountered in source text. Instances of this exception provide three
54-
interesting attributes: :attr:`msg` is a textual explanation of the error,
55-
:attr:`filename` is the name of the source file, and :attr:`lineno` gives the
56-
line number on which the error was found.
54+
interesting attributes:
55+
56+
.. attribute:: msg
57+
58+
Textual explanation of the error.
59+
60+
.. attribute:: filename
61+
62+
The name of the source file.
63+
64+
.. attribute:: lineno
65+
66+
The line number on which the error was found.
5767

5868

5969
.. _netrc-objects:

‎Doc/library/operator.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,9 @@ truth tests, identity tests, and boolean operations:
5959
__not__(obj)
6060

6161
Return the outcome of :keyword:`not` *obj*. (Note that there is no
62-
:meth:`__not__` method for object instances; only the interpreter core defines
63-
this operation. The result is affected by the :meth:`__bool__` and
64-
:meth:`__len__` methods.)
62+
:meth:`!__not__` method for object instances; only the interpreter core defines
63+
this operation. The result is affected by the :meth:`~object.__bool__` and
64+
:meth:`~object.__len__` methods.)
6565

6666

6767
.. function:: truth(obj)

‎Doc/library/poplib.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ A :class:`POP3` instance has the following methods:
148148
.. method:: POP3.pass_(password)
149149

150150
Send password, response includes message count and mailbox size. Note: the
151-
mailbox on the server is locked until :meth:`~poplib.quit` is called.
151+
mailbox on the server is locked until :meth:`~POP3.quit` is called.
152152

153153

154154
.. method:: POP3.apop(user, secret)

0 commit comments

Comments
 (0)
0