Move parts of Enum how-to to API docs

To avoid duplicate content in the Enum HOWTO and
API documentation which is not automatically synced,
the section about supported __dunder__ and _sunder
names is moved from HOWTO to API docs.

See also #136791

Author: RafaelWO

Doc/howto/enum.rst

@@ -967,69 +967,10 @@ want one of them to be the value::
 Finer Points
 ^^^^^^^^^^^^
 
-Supported ``__dunder__`` names
-""""""""""""""""""""""""""""""
+Supported ``__dunder__`` and ``_sunder_`` names
+"""""""""""""""""""""""""""""""""""""""""""""""
 
-:attr:`~enum.EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
-items.  It is only available on the class.
-
-:meth:`~object.__new__`, if specified, must create and return the enum members; it is
-also a very good idea to set the member's :attr:`~Enum._value_` appropriately.  Once
-all the members are created it is no longer used.
-
-
-Supported ``_sunder_`` names
-""""""""""""""""""""""""""""
-
-- :attr:`~Enum._name_` -- name of the member
-- :attr:`~Enum._value_` -- value of the member; can be set in ``__new__``
-- :meth:`~Enum._missing_` -- a lookup function used when a value is not found;
-  may be overridden
-- :attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a
-  :class:`str`, that will not be transformed into members, and will be removed
-  from the final class
-- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
-  an enum member; may be overridden
-- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
-  member.
-- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
-  existing member.  See `MultiValueEnum`_ for an example.
-
-  .. note::
-
-     For standard :class:`Enum` classes the next value chosen is the highest
-     value seen incremented by one.
-
-     For :class:`Flag` classes the next value chosen will be the next highest
-     power-of-two.
-
-  .. versionchanged:: 3.13
-     Prior versions would use the last seen value instead of the highest value.
-
-.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
-.. versionadded:: 3.7 ``_ignore_``
-.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``
-
-To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` attribute can
-be provided.  It will be checked against the actual order of the enumeration
-and raise an error if the two do not match::
-
-    >>> class Color(Enum):
-    ...     _order_ = 'RED GREEN BLUE'
-    ...     RED = 1
-    ...     BLUE = 3
-    ...     GREEN = 2
-    ...
-    Traceback (most recent call last):
-    ...
-    TypeError: member order does not match _order_:
-      ['RED', 'BLUE', 'GREEN']
-      ['RED', 'GREEN', 'BLUE']
-
-.. note::
-
-    In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
-    order is lost before it can be recorded.
+The supported ``__dunder__`` and ``_sunder_`` names can be found in the :ref:`Enum API documentation <enum-dunder-sunder>`.
 
 
 _Private__names
@@ -1478,6 +1419,7 @@ alias::
     behaviors as well as disallowing aliases.  If the only desired change is
     disallowing aliases, the :func:`unique` decorator can be used instead.
 
+.. _multi-value-enum:
 
 MultiValueEnum
 ^^^^^^^^^^^^^^^^^

Doc/library/enum.rst

@@ -301,6 +301,26 @@ Data Types
       No longer used, kept for backward compatibility.
       (class attribute, removed during class creation).
 
+      The :attr:`~Enum._order_` attribute can be provided to help keep Python 2 / Python 3 code in sync.
+      It will be checked against the actual order of the enumeration and raise an error if the two do not match::
+
+         >>> class Color(Enum):
+         ...     _order_ = 'RED GREEN BLUE'
+         ...     RED = 1
+         ...     BLUE = 3
+         ...     GREEN = 2
+         ...
+         Traceback (most recent call last):
+         ...
+         TypeError: member order does not match _order_:
+            ['RED', 'BLUE', 'GREEN']
+            ['RED', 'GREEN', 'BLUE']
+
+      .. note::
+
+         In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
+         order is lost before it can be recorded.
+
    .. attribute:: Enum._ignore_
 
       ``_ignore_`` is only used during creation and is removed from the
@@ -480,7 +500,8 @@ Data Types
          >>> Color(42)
          <Color.RED: 1>
 
-      Raises a :exc:`ValueError` if the value is already linked with a different member.
+      | Raises a :exc:`ValueError` if the value is already linked with a different member.
+      | See :ref:`multi-value-enum` for an example.
 
       .. versionadded:: 3.13
 
@@ -879,14 +900,16 @@ Data Types
 
 ---------------
 
+.. _enum-dunder-sunder:
+
 Supported ``__dunder__`` names
 """"""""""""""""""""""""""""""
 
 :attr:`~EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
 items.  It is only available on the class.
 
 :meth:`~Enum.__new__`, if specified, must create and return the enum members;
-it is also a very good idea to set the member's :attr:`!_value_` appropriately.
+it is also a very good idea to set the member's :attr:`~Enum._value_` appropriately.
 Once all the members are created it is no longer used.
 
 
@@ -902,6 +925,7 @@ Supported ``_sunder_`` names
   from the final class
 - :attr:`~Enum._order_` -- no longer used, kept for backward
   compatibility (class attribute, removed during class creation)
+
 - :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
   an enum member; may be overridden