doc: Create autodoc extension tutorial

1 files changed, 52 insertions, 0 deletions

diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
new file mode 100644
index 000000000..7fb85d066
--- /dev/null
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -0,0 +1,52 @@
+from enum import IntEnum
+from typing import Any, Optional
+
+from docutils.statemachine import StringList
+
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
+
+
+class IntEnumDocumenter(ClassDocumenter):
+    objtype = 'intenum'
+    directivetype = 'class'
+    priority = 10 + ClassDocumenter.priority
+    option_spec = dict(ClassDocumenter.option_spec)
+    option_spec['hex'] = bool_option
+
+    @classmethod
+    def can_document_member(cls,
+                            member: Any, membername: str,
+                            isattr: bool, parent: Any) -> bool:
+        return isinstance(member, IntEnum)
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+        self.add_line('   :final:', self.get_sourcename())
+
+    def add_content(self,
+                    more_content: Optional[StringList],
+                    no_docstring: bool = False
+                    ) -> None:
+
+        super().add_content(more_content, no_docstring)
+
+        source_name = self.get_sourcename()
+        enum_object: IntEnum = self.object
+        use_hex = self.options.hex
+        self.add_line('', source_name)
+
+        for enum_value in enum_object:
+            the_value_name = enum_value.name
+            the_value_value = enum_value.value
+            if use_hex:
+                the_value_value = hex(the_value_value)
+
+            self.add_line(
+                f"**{the_value_name}**: {the_value_value}", source_name)
+            self.add_line('', source_name)
+
+
+def setup(app: Sphinx) -> None:
+    app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
+    app.add_autodocumenter(IntEnumDocumenter)