bpo-30052: Link `bytes` & `bytearray` to stdtypes not functions (GH-1271) (GH-1915)

Builtin container types have two potential link targets in the docs:

- their entry in the list of builtin callables
- their type documentation

This change brings `bytes` and `bytearray` into line with other
container types by having cross-references default to linking to
their type documentation, rather than their builtin callable entry..
(cherry picked from commit c6db4811f9)

Doc/library/functions.rst

@@ -16,8 +16,8 @@ are always available.  They are listed here in alphabetical order.
 :func:`ascii`        :func:`enumerate`  :func:`input`       :func:`oct`       :func:`staticmethod`
 :func:`bin`          :func:`eval`       :func:`int`         :func:`open`      |func-str|_
 :func:`bool`         :func:`exec`       :func:`isinstance`  :func:`ord`       :func:`sum`
-:func:`bytearray`    :func:`filter`     :func:`issubclass`  :func:`pow`       :func:`super`
-:func:`bytes`        :func:`float`      :func:`iter`        :func:`print`     |func-tuple|_
+|func-bytearray|_    :func:`filter`     :func:`issubclass`  :func:`pow`       :func:`super`
+|func-bytes|_        :func:`float`      :func:`iter`        :func:`print`     |func-tuple|_
 :func:`callable`     :func:`format`     :func:`len`         :func:`property`  :func:`type`
 :func:`chr`          |func-frozenset|_  |func-list|_        |func-range|_     :func:`vars`
 :func:`classmethod`  :func:`getattr`    :func:`locals`      :func:`repr`      :func:`zip`
@@ -37,7 +37,8 @@ are always available.  They are listed here in alphabetical order.
 .. |func-str| replace:: ``str()``
 .. |func-tuple| replace:: ``tuple()``
 .. |func-range| replace:: ``range()``
-
+.. |func-bytearray| replace:: ``bytearray()``
+.. |func-bytes| replace:: ``bytes()``
 
 .. function:: abs(x)
 
@@ -99,6 +100,7 @@ are always available.  They are listed here in alphabetical order.
 
 .. _func-bytearray:
 .. class:: bytearray([source[, encoding[, errors]]])
+   :noindex:
 
    Return a new array of bytes.  The :class:`bytearray` class is a mutable
    sequence of integers in the range 0 <= x < 256.  It has most of the usual
@@ -128,6 +130,7 @@ are always available.  They are listed here in alphabetical order.
 
 .. _func-bytes:
 .. class:: bytes([source[, encoding[, errors]]])
+   :noindex:
 
    Return a new "bytes" object, which is an immutable sequence of integers in
    the range ``0 <= x < 256``.  :class:`bytes` is an immutable version of

Doc/library/stdtypes.rst

@@ -2264,8 +2264,8 @@ The :mod:`array` module supports efficient storage of basic data types like
 
 .. _typebytes:
 
-Bytes
------
+Bytes Objects
+-------------
 
 .. index:: object: bytes
 
@@ -2274,6 +2274,8 @@ binary protocols are based on the ASCII text encoding, bytes objects offer
 several methods that are only valid when working with ASCII compatible
 data and are closely related to string objects in a variety of other ways.
 
+.. class:: bytes([source[, encoding[, errors]]])
+
    Firstly, the syntax for bytes literals is largely the same as that for string
    literals, except that a ``b`` prefix is added:
 
@@ -2312,11 +2314,11 @@ Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
    numbers are a commonly used format for describing binary data. Accordingly,
    the bytes type has an additional class method to read data in that format:
 
-.. classmethod:: bytes.fromhex(string)
+   .. classmethod:: fromhex(string)
 
       This :class:`bytes` class method returns a bytes object, decoding the
       given string object.  The string must contain two hexadecimal digits per
-   byte, with ASCII spaces being ignored.
+      byte, with ASCII whitespace being ignored.
 
       >>> bytes.fromhex('2Ef0 F1f2  ')
       b'.\xf0\xf1\xf2'
@@ -2324,7 +2326,7 @@ the bytes type has an additional class method to read data in that format:
    A reverse conversion function exists to transform a bytes object into its
    hexadecimal representation.
 
-.. method:: bytes.hex()
+   .. method:: hex()
 
       Return a string object containing two hexadecimal digits for each
       byte in the instance.
@@ -2362,7 +2364,11 @@ Bytearray Objects
 .. index:: object: bytearray
 
 :class:`bytearray` objects are a mutable counterpart to :class:`bytes`
-objects. There is no dedicated literal syntax for bytearray objects, instead
+objects.
+
+.. class:: bytearray([source[, encoding[, errors]]])
+
+   There is no dedicated literal syntax for bytearray objects, instead
    they are always created by calling the constructor:
 
    * Creating an empty instance: ``bytearray()``
@@ -2380,11 +2386,11 @@ Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
    numbers are a commonly used format for describing binary data. Accordingly,
    the bytearray type has an additional class method to read data in that format:
 
-.. classmethod:: bytearray.fromhex(string)
+   .. classmethod:: fromhex(string)
 
       This :class:`bytearray` class method returns bytearray object, decoding
       the given string object.  The string must contain two hexadecimal digits
-   per byte, with ASCII spaces being ignored.
+      per byte, with ASCII whitespace being ignored.
 
       >>> bytearray.fromhex('2Ef0 F1f2  ')
       bytearray(b'.\xf0\xf1\xf2')
@@ -2392,7 +2398,7 @@ the bytearray type has an additional class method to read data in that format:
    A reverse conversion function exists to transform a bytearray object into its
    hexadecimal representation.
 
-.. method:: bytearray.hex()
+   .. method:: hex()
 
       Return a string object containing two hexadecimal digits for each
       byte in the instance.

Doc/reference/datamodel.rst

@@ -320,9 +320,9 @@ Sequences
 
          A bytes object is an immutable array.  The items are 8-bit bytes,
          represented by integers in the range 0 <= x < 256.  Bytes literals
-         (like ``b'abc'``) and the built-in function :func:`bytes` can be used to
-         construct bytes objects.  Also, bytes objects can be decoded to strings
-         via the :meth:`~bytes.decode` method.
+         (like ``b'abc'``) and the built-in :func:`bytes()` constructor
+         can be used to create bytes objects.  Also, bytes objects can be
+         decoded to strings via the :meth:`~bytes.decode` method.
 
    Mutable sequences
       .. index::
@@ -349,9 +349,9 @@ Sequences
          .. index:: bytearray
 
          A bytearray object is a mutable array. They are created by the built-in
-         :func:`bytearray` constructor.  Aside from being mutable (and hence
-         unhashable), byte arrays otherwise provide the same interface and
-         functionality as immutable bytes objects.
+         :func:`bytearray` constructor.  Aside from being mutable
+         (and hence unhashable), byte arrays otherwise provide the same interface
+         and functionality as immutable :class:`bytes` objects.
 
       .. index:: module: array
 
@@ -1253,8 +1253,8 @@ Basic customization
 
    .. index:: builtin: bytes
 
-   Called by :func:`bytes` to compute a byte-string representation of an
-   object. This should return a ``bytes`` object.
+   Called by :ref:`bytes <func-bytes>` to compute a byte-string representation
+   of an object. This should return a :class:`bytes` object.
 
    .. index::
       single: string; __format__() (object method)