Documentation: Change Enum page to be a proper decorator

Split out QFlag to a separate page for proper indexing.

Task-number: PYSIDE-1106
Task-number: PYSIDE-2215
Change-Id: Ibf4e1ad045c272adfa7c0a47bb2fe7ff1781d100
Reviewed-by: Adrian Herrmann <adrian.herrmann@qt.io>

2 files changed, 84 insertions, 74 deletions

diff --git a/sources/pyside6/doc/extras/QtCore.QEnum.rst b/sources/pyside6/doc/extras/QtCore.QEnum.rst
index d42da91ab..7ea35d8af 100644
--- a/sources/pyside6/doc/extras/QtCore.QEnum.rst
+++ b/sources/pyside6/doc/extras/QtCore.QEnum.rst
@@ -1,23 +1,19 @@
 .. currentmodule:: PySide6.QtCore
-.. _QEnum:
-
-QEnum/QFlag
-***********
-
-This class decorator is equivalent to the `Q_ENUM` macro from Qt.
-The decorator is used to register an Enum to the meta-object system,
-which is available via `QObject.staticMetaObject`.
-The enumerator must be in a QObject derived class to be registered.
+.. py:decorator:: QEnum
 
+This class decorator is equivalent to the `Q_ENUM` macro from Qt. The decorator
+is used to register a Python Enum derived class to the meta-object system,
+which is available via `QObject.staticMetaObject`. The enumerator must be in a
+QObject derived class to be registered.
 
 Example
 -------
 
 ::
 
-    from enum import Enum, Flag, auto
+    from enum import Enum, auto
 
-    from PySide6.QtCore import QEnum, QFlag, QObject
+    from PySide6.QtCore import QEnum, QObject
 
     class Demo(QObject):
 
@@ -25,67 +21,7 @@ Example
         class Orientation(Enum):
             North, East, South, West = range(4)
 
-        class Color(Flag):
-            RED = auto()
-            BLUE = auto()
-            GREEN = auto()
-            WHITE = RED | BLUE | GREEN
-
-        QFlag(Color)    # identical to @QFlag usage
-
-
-Caution:
---------
-
-QEnum registers a Python Enum derived class.
-QFlag treats a variation of the Python Enum, the Flag class.
-
-Please do not confuse that with the Qt QFlags concept. Python does
-not use that concept, it has its own class hierarchy, instead.
-For more details, see the `Python enum documentation <https://docs.python.org/3/library/enum.html>`_.
-
-
-Details about Qt Flags:
------------------------
-
-There are some small differences between Qt flags and Python flags.
-In Qt, we have for instance these declarations:
-
-::
-
-    enum    QtGui::RenderHint { Antialiasing, TextAntialiasing, SmoothPixmapTransform,
-                                HighQualityAntialiasing, NonCosmeticDefaultPen }
-    flags   QtGui::RenderHints
-
-The equivalent Python notation would look like this:
-
-::
-
-    @QFlag
-    class RenderHints(enum.Flag)
-        Antialiasing = auto()
-        TextAntialiasing = auto()
-        SmoothPixmapTransform = auto()
-        HighQualityAntialiasing = auto()
-        NonCosmeticDefaultPen = auto()
-
-
-As another example, the Qt::AlignmentFlag flag has 'AlignmentFlag' as the enum
-name, but 'Alignment' as the type name. Non flag enums have the same type and
-enum names.
-
-::
-
-    enum Qt::AlignmentFlag
-    flags Qt::Alignment
-
-The Python way to specify this would be
-
-::
-
-    @QFlag
-    class Alignment(enum.Flag):
-        ...
+See :deco:`QFlag` for registering Python Flag derived classes.
 
-Meanwhile we have converted all enums and flags to Python Enums (optional in ``PySide 6.3``,
-default in ``PySide 6.4``), see the :ref:`NewEnumSystem` section.
+Meanwhile all enums and flags have been converted to Python Enums
+(default since ``PySide 6.4``), see the :ref:`NewEnumSystem` section.
diff --git a/sources/pyside6/doc/extras/QtCore.QFlag.rst b/sources/pyside6/doc/extras/QtCore.QFlag.rst
new file mode 100644
index 000000000..dd4f02800
--- /dev/null
+++ b/sources/pyside6/doc/extras/QtCore.QFlag.rst
@@ -0,0 +1,74 @@
+.. currentmodule:: PySide6.QtCore
+.. py:decorator:: QFlag
+
+QFlag handles a variation of the Python Enum, the Flag class.
+
+Please do not confuse that with the Qt QFlags concept. Python does
+not use that concept, it has its own class hierarchy, instead.
+For more details, see the `Python enum documentation <https://docs.python.org/3/library/enum.html>`_.
+
+Example
+-------
+
+::
+
+    from enum import Flag, auto
+
+    from PySide6.QtCore import QFlag, QObject
+
+    class Demo(QObject):
+
+        @QFlag
+        class Color(Flag):
+            RED = auto()
+            BLUE = auto()
+            GREEN = auto()
+            WHITE = RED | BLUE | GREEN
+
+
+Details about Qt Flags:
+-----------------------
+
+There are some small differences between Qt flags and Python flags.
+In Qt, we have for instance these declarations:
+
+::
+
+    enum    QtGui::RenderHint { Antialiasing, TextAntialiasing, SmoothPixmapTransform,
+                                HighQualityAntialiasing, NonCosmeticDefaultPen }
+    flags   QtGui::RenderHints
+
+The equivalent Python notation would look like this:
+
+::
+
+    @QFlag
+    class RenderHints(enum.Flag)
+        Antialiasing = auto()
+        TextAntialiasing = auto()
+        SmoothPixmapTransform = auto()
+        HighQualityAntialiasing = auto()
+        NonCosmeticDefaultPen = auto()
+
+
+As another example, the Qt::AlignmentFlag flag has 'AlignmentFlag' as the enum
+name, but 'Alignment' as the type name. Non flag enums have the same type and
+enum names.
+
+::
+
+    enum Qt::AlignmentFlag
+    flags Qt::Alignment
+
+The Python way to specify this would be
+
+::
+
+    @QFlag
+    class Alignment(enum.Flag):
+        ...
+
+See :deco:`QEnum` for registering Python Enum derived classes.
+
+Meanwhile all enums and flags have been converted to Python Enums
+(default since ``PySide 6.4``), see the :ref:`NewEnumSystem` section.