Close #18908: Keep Enum docs in their own section. Patch by Elazar Gershuni.

Doc/library/enum.rst

@@ -36,11 +36,15 @@ follows::
     ...     red = 1
     ...     green = 2
     ...     blue = 3
+    ...
 
-**A note on nomenclature**: we call :class:`Color` an *enumeration* (or *enum*)
+..note: Nomenclature
-and :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or
+  - The class :class:`Color` is an *enumeration* (or *enum*)
-*enum members*).  Enumeration members also have *values* (the value of
+  - The attributes :attr:`Color.red`, :attr:`Color.green`, etc., are
-:attr:`Color.red` is ``1``, etc.)
+    *enumeration members* (or *enum members*).
+  - The enum members have *names* and *values* (the name of
+    :attr:`Color.red` is ``red``, the value of :attr:`Color.blue` is
+    ``3``, etc.)
 
 Enumeration members have human readable string representations::
 
@@ -151,7 +155,7 @@ return A::
 
 
 Ensuring unique enumeration values
-==================================
+----------------------------------
 
 By default, enumerations allow multiple names as aliases for the same value.
 When this behavior isn't desired, the following decorator can be used to
@@ -170,13 +174,14 @@ found :exc:`ValueError` is raised with the details::
     ...     two = 2
     ...     three = 3
     ...     four = 3
+    ...
     Traceback (most recent call last):
     ...
     ValueError: duplicate values found in <enum 'Mistake'>: four -> three
 
 
 Iteration
-=========
+---------
 
 Iterating over the members of an enum does not provide the aliases::
 
@@ -266,6 +271,7 @@ usual.  If we have this enumeration::
     ...     def favorite_mood(cls):
     ...         # cls here is the enumeration
     ...         return cls.happy
+    ...
 
 Then::
 
@@ -295,6 +301,7 @@ any members.  So this is forbidden::
 
     >>> class MoreColor(Color):
     ...     pink = 17
+    ...
     Traceback (most recent call last):
     ...
     TypeError: Cannot extend enumerations
@@ -367,6 +374,7 @@ assignment to :class:`Animal` is equivalent to::
     ...     bee = 2
     ...     cat = 3
     ...     dog = 4
+    ...
 
 The reason for defaulting to ``1`` as the starting number and not ``0`` is
 that ``0`` is ``False`` in a boolean sense, but enum members all evaluate
@@ -381,10 +389,10 @@ The solution is to specify the module name explicitly as follows::
     >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__)
 
 Derived Enumerations
-====================
+--------------------
 
 IntEnum
--------
+^^^^^^^
 
 A variation of :class:`Enum` is provided which is also a subclass of
 :class:`int`.  Members of an :class:`IntEnum` can be compared to integers;
@@ -439,7 +447,7 @@ that still expects integers.
 
 
 Others
-------
+^^^^^^
 
 While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
 simple to implement independently::
@@ -472,7 +480,7 @@ Some rules:
 
 
 Interesting examples
-====================
+--------------------
 
 While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of
 use-cases, they cannot cover them all.  Here are recipes for some different
@@ -481,7 +489,7 @@ one's own.
 
 
 AutoNumber
-----------
+^^^^^^^^^^
 
 Avoids having to specify the value for each enumeration member::
 
@@ -502,7 +510,7 @@ Avoids having to specify the value for each enumeration member::
 
 
 OrderedEnum
------------
+^^^^^^^^^^^
 
 An ordered enumeration that is not based on :class:`IntEnum` and so maintains
 the normal :class:`Enum` invariants (such as not being comparable to other
@@ -538,7 +546,7 @@ enumerations)::
 
 
 DuplicateFreeEnum
------------------
+^^^^^^^^^^^^^^^^^
 
 Raises an error if a duplicate member name is found instead of creating an
 alias::
@@ -558,6 +566,7 @@ alias::
     ...     green = 2
     ...     blue = 3
     ...     grene = 2
+    ...
     Traceback (most recent call last):
     ...
     ValueError: aliases not allowed in DuplicateFreeEnum:  'grene' --> 'green'
@@ -570,7 +579,7 @@ alias::
 
 
 Planet
-------
+^^^^^^
 
 If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
 will be passed to those methods::