From b14dd067863b787aa8e266eb2a5a2cef558c2c2e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 13 Aug 2020 17:24:39 +0200 Subject: [PATCH 1/3] bpo-40204: Add :noindex: in the documentation Add :noindex: to duplicated documentation to fix "duplicate object description" errors. For example, fix this Sphinx 3 issue: Doc/library/configparser.rst:1146: WARNING: duplicate object description of configparser.ConfigParser.optionxform, other instance in library/configparser, use :noindex: for one of them --- Doc/library/aifc.rst | 2 ++ Doc/library/configparser.rst | 1 + Doc/library/difflib.rst | 2 ++ Doc/library/enum.rst | 1 + Doc/library/socket.rst | 2 ++ Doc/library/string.rst | 1 + Doc/library/tarfile.rst | 1 + Doc/library/turtle.rst | 3 +++ Doc/library/urllib.request.rst | 2 +- Doc/reference/introduction.rst | 1 + 10 files changed, 15 insertions(+), 1 deletion(-) diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index 7328907730fb107..2e917cf7321b857 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -208,6 +208,7 @@ number of frames must be filled in. .. method:: aifc.tell() + :noindex: Return the current write position in the output file. Useful in combination with :meth:`setmark`. @@ -232,6 +233,7 @@ number of frames must be filled in. .. method:: aifc.close() + :noindex: Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 739477f55fddda8..e2998fed764035b 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -696,6 +696,7 @@ be overridden by subclasses or by attribute assignment. ``enabled``/``disabled``. .. method:: ConfigParser.optionxform(option) + :noindex: This method transforms option names on every read, get, or set operation. The default converts the name to lowercase. This also diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 7a898c21b52e03b..25e3511d017858f 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -24,6 +24,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. .. class:: SequenceMatcher + :noindex: This is a flexible class for comparing pairs of sequences of any type, so long as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a @@ -651,6 +652,7 @@ The :class:`Differ` class has this constructor: .. class:: Differ(linejunk=None, charjunk=None) + :noindex: Optional keyword parameters *linejunk* and *charjunk* are for filter functions (or ``None``): diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index b327a0ad15f96c9..00bfb260c020472 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -50,6 +50,7 @@ helper, :class:`auto`. the bitwise operations without losing their :class:`Flag` membership. .. function:: unique + :noindex: Enum class decorator that ensures only one name is bound to any one value. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index d798c1a9d10a059..5bcac20a4c60485 100755 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1695,7 +1695,9 @@ to sockets. .. method:: socket.setsockopt(level, optname, value: int) .. method:: socket.setsockopt(level, optname, value: buffer) + :noindex: .. method:: socket.setsockopt(level, optname, None, optlen: int) + :noindex: .. index:: module: struct diff --git a/Doc/library/string.rst b/Doc/library/string.rst index fa906f799c1082c..7662ee75961f528 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -206,6 +206,7 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``. The grammar for a replacement field is as follows: .. productionlist:: sf + :noindex: replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* arg_name: [`identifier` | `digit`+] diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index c204263d3a094c1..cca466b56979487 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -151,6 +151,7 @@ Some facts and figures: .. class:: TarFile + :noindex: Class for reading and writing tar archives. Do not use this class directly: use :func:`tarfile.open` instead. See :ref:`tarfile-objects`. diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index fed85045435b1b6..d3487537df99a95 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -1069,6 +1069,7 @@ More drawing control ~~~~~~~~~~~~~~~~~~~~ .. function:: reset() + :noindex: Delete the turtle's drawings from the screen, re-center the turtle and set variables to the default values. @@ -1090,6 +1091,7 @@ More drawing control .. function:: clear() + :noindex: Delete the turtle's drawings from the screen. Do not move turtle. State and position of the turtle as well as drawings of other turtles are not affected. @@ -1362,6 +1364,7 @@ Using events ------------ .. function:: onclick(fun, btn=1, add=None) + :noindex: :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 288ce14d36f0163..b37f230feb60153 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -946,7 +946,7 @@ tracking URIs for which authentication credentials should always be sent. If *is_authenticated* is specified as ``True``, *realm* is ignored. -.. method:: HTTPPasswordMgr.find_user_password(realm, authuri) +.. method:: HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri) Same as for :class:`HTTPPasswordMgrWithDefaultRealm` objects diff --git a/Doc/reference/introduction.rst b/Doc/reference/introduction.rst index bb7e3906dba6072..4754473bdc6ad9f 100644 --- a/Doc/reference/introduction.rst +++ b/Doc/reference/introduction.rst @@ -94,6 +94,7 @@ The descriptions of lexical analysis and syntax use a modified BNF grammar notation. This uses the following style of definition: .. productionlist:: * + :noindex: name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" From 2ddd1af3942ed269ac7243f23da320d22eebb418 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 13 Aug 2020 18:51:59 +0200 Subject: [PATCH 2/3] Fix indentation --- Doc/library/configparser.rst | 160 +++++++++++++++++------------------ 1 file changed, 80 insertions(+), 80 deletions(-) diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index e2998fed764035b..2e22a549ee2813d 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -674,98 +674,98 @@ be overridden by subclasses or by attribute assignment. .. attribute:: ConfigParser.BOOLEAN_STATES - By default when using :meth:`~ConfigParser.getboolean`, config parsers - consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``, - ``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``, - ``'off'``. You can override this by specifying a custom dictionary of strings - and their Boolean outcomes. For example: - - .. doctest:: - - >>> custom = configparser.ConfigParser() - >>> custom['section1'] = {'funky': 'nope'} - >>> custom['section1'].getboolean('funky') - Traceback (most recent call last): - ... - ValueError: Not a boolean: nope - >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False} - >>> custom['section1'].getboolean('funky') - False - - Other typical Boolean pairs include ``accept``/``reject`` or - ``enabled``/``disabled``. + By default when using :meth:`~ConfigParser.getboolean`, config parsers + consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``, + ``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``, + ``'off'``. You can override this by specifying a custom dictionary of strings + and their Boolean outcomes. For example: + + .. doctest:: + + >>> custom = configparser.ConfigParser() + >>> custom['section1'] = {'funky': 'nope'} + >>> custom['section1'].getboolean('funky') + Traceback (most recent call last): + ... + ValueError: Not a boolean: nope + >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False} + >>> custom['section1'].getboolean('funky') + False + + Other typical Boolean pairs include ``accept``/``reject`` or + ``enabled``/``disabled``. .. method:: ConfigParser.optionxform(option) :noindex: - This method transforms option names on every read, get, or set - operation. The default converts the name to lowercase. This also - means that when a configuration file gets written, all keys will be - lowercase. Override this method if that's unsuitable. - For example: + This method transforms option names on every read, get, or set + operation. The default converts the name to lowercase. This also + means that when a configuration file gets written, all keys will be + lowercase. Override this method if that's unsuitable. + For example: - .. doctest:: + .. doctest:: + + >>> config = """ + ... [Section1] + ... Key = Value + ... + ... [Section2] + ... AnotherKey = Value + ... """ + >>> typical = configparser.ConfigParser() + >>> typical.read_string(config) + >>> list(typical['Section1'].keys()) + ['key'] + >>> list(typical['Section2'].keys()) + ['anotherkey'] + >>> custom = configparser.RawConfigParser() + >>> custom.optionxform = lambda option: option + >>> custom.read_string(config) + >>> list(custom['Section1'].keys()) + ['Key'] + >>> list(custom['Section2'].keys()) + ['AnotherKey'] - >>> config = """ - ... [Section1] - ... Key = Value - ... - ... [Section2] - ... AnotherKey = Value - ... """ - >>> typical = configparser.ConfigParser() - >>> typical.read_string(config) - >>> list(typical['Section1'].keys()) - ['key'] - >>> list(typical['Section2'].keys()) - ['anotherkey'] - >>> custom = configparser.RawConfigParser() - >>> custom.optionxform = lambda option: option - >>> custom.read_string(config) - >>> list(custom['Section1'].keys()) - ['Key'] - >>> list(custom['Section2'].keys()) - ['AnotherKey'] - - .. note:: - The optionxform function transforms option names to a canonical form. - This should be an idempotent function: if the name is already in - canonical form, it should be returned unchanged. + .. note:: + The optionxform function transforms option names to a canonical form. + This should be an idempotent function: if the name is already in + canonical form, it should be returned unchanged. .. attribute:: ConfigParser.SECTCRE - A compiled regular expression used to parse section headers. The default - matches ``[section]`` to the name ``"section"``. Whitespace is considered - part of the section name, thus ``[ larch ]`` will be read as a section of - name ``" larch "``. Override this attribute if that's unsuitable. For - example: + A compiled regular expression used to parse section headers. The default + matches ``[section]`` to the name ``"section"``. Whitespace is considered + part of the section name, thus ``[ larch ]`` will be read as a section of + name ``" larch "``. Override this attribute if that's unsuitable. For + example: + + .. doctest:: + + >>> import re + >>> config = """ + ... [Section 1] + ... option = value + ... + ... [ Section 2 ] + ... another = val + ... """ + >>> typical = configparser.ConfigParser() + >>> typical.read_string(config) + >>> typical.sections() + ['Section 1', ' Section 2 '] + >>> custom = configparser.ConfigParser() + >>> custom.SECTCRE = re.compile(r"\[ *(?P
[^]]+?) *\]") + >>> custom.read_string(config) + >>> custom.sections() + ['Section 1', 'Section 2'] - .. doctest:: + .. note:: - >>> import re - >>> config = """ - ... [Section 1] - ... option = value - ... - ... [ Section 2 ] - ... another = val - ... """ - >>> typical = configparser.ConfigParser() - >>> typical.read_string(config) - >>> typical.sections() - ['Section 1', ' Section 2 '] - >>> custom = configparser.ConfigParser() - >>> custom.SECTCRE = re.compile(r"\[ *(?P
[^]]+?) *\]") - >>> custom.read_string(config) - >>> custom.sections() - ['Section 1', 'Section 2'] - - .. note:: - - While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing - option lines, it's not recommended to override it because that would - interfere with constructor options *allow_no_value* and *delimiters*. + While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing + option lines, it's not recommended to override it because that would + interfere with constructor options *allow_no_value* and *delimiters*. Legacy API Examples From 1927132c6c1577d1f79969f1fc3568053da5be6d Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 13 Aug 2020 19:12:47 +0200 Subject: [PATCH 3/3] Add :noindex: to token.TYPE_COMMENT And don't use ":noindex:" on productionlist. --- Doc/library/string.rst | 1 - Doc/library/token.rst | 1 + Doc/reference/introduction.rst | 1 - 3 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 7662ee75961f528..fa906f799c1082c 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -206,7 +206,6 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``. The grammar for a replacement field is as follows: .. productionlist:: sf - :noindex: replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* arg_name: [`identifier` | `digit`+] diff --git a/Doc/library/token.rst b/Doc/library/token.rst index f8ebb275ebbc444..a1aceba96ce0306 100644 --- a/Doc/library/token.rst +++ b/Doc/library/token.rst @@ -70,6 +70,7 @@ the :mod:`tokenize` module. .. data:: TYPE_COMMENT + :noindex: Token value indicating that a type comment was recognized. Such tokens are only produced when :func:`ast.parse()` is invoked with diff --git a/Doc/reference/introduction.rst b/Doc/reference/introduction.rst index 4754473bdc6ad9f..bb7e3906dba6072 100644 --- a/Doc/reference/introduction.rst +++ b/Doc/reference/introduction.rst @@ -94,7 +94,6 @@ The descriptions of lexical analysis and syntax use a modified BNF grammar notation. This uses the following style of definition: .. productionlist:: * - :noindex: name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z"