docs: move extension command- and url-related API to own API pages (#1093)

* docs: move extension command- and url-related API to own API pages

* refactor: fix linters

docs/scripts/reference.py

@@ -95,6 +95,9 @@ def gen_reference_api():
                 or _is_error_cls(obj)
                 or _is_tag_formatter_instance(obj)
                 or _is_tag_formatter_cls(obj)
+                or _is_extension_command_api(obj)
+                or _is_extension_hook_api(obj)
+                or _is_extension_url_api(obj)
             ):
                 continue
 
@@ -660,6 +663,7 @@ def gen_reference_extension_hooks():
         # All hooks start with `on_`, so filter out the rest
         unique_methods = [name for name in unique_methods if name.startswith("on_")]
 
+        f.write("## Hooks\n\n")
         for name in sorted(unique_methods):
             # Programmatically get the data available inside the hook, so we can generate
             # a table of available data.
@@ -691,6 +695,7 @@ def gen_reference_extension_hooks():
             f.write(
                 f"::: {class_name}.{name}\n"
                 f"    options:\n"
+                f"      heading_level: 3\n"
                 f"      show_root_heading: true\n"
                 f"      show_signature: true\n"
                 f"      separate_signature: true\n"
@@ -703,6 +708,102 @@ def gen_reference_extension_hooks():
             f.write(available_data)
             f.write("\n")
 
+        # 3. Print the context objects for each hook
+        f.write("## Objects\n\n")
+        main_module = import_module("django_components")
+        for name, obj in inspect.getmembers(main_module):
+            if not _is_extension_hook_api(obj):
+                continue
+
+            # For each entry, generate a mkdocstrings entry, e.g.
+            # ```
+            # ::: django_components.extension.OnComponentClassCreatedContext
+            #     options:
+            #       show_if_no_docstring: true
+            # ```
+            f.write(
+                f"::: {module.__name__}.{name}\n"
+                f"    options:\n"
+                f"      heading_level: 3\n"
+                f"      show_if_no_docstring: true\n"
+            )
+
+            f.write("\n")
+
+
+def gen_reference_extension_commands():
+    """
+    Generate documentation for the objects related to defining extension commands.
+    """
+    module = import_module("django_components")
+
+    preface = "<!-- Autogenerated by reference.py -->\n\n"
+    preface += (root / "docs/templates/reference_extension_commands.md").read_text()
+    out_file = root / "docs/reference/extension_commands.md"
+
+    out_file.parent.mkdir(parents=True, exist_ok=True)
+    with out_file.open("w", encoding="utf-8") as f:
+        # 1. Insert section from `reference_extension_commands.md`
+        f.write(preface + "\n\n")
+
+        # 2. Print the context objects for each hook
+        main_module = import_module("django_components")
+        for name, obj in inspect.getmembers(main_module):
+            if not _is_extension_command_api(obj):
+                continue
+
+            # For each entry, generate a mkdocstrings entry, e.g.
+            # ```
+            # ::: django_components.util.command.CommandLiteralAction
+            #     options:
+            #       show_if_no_docstring: true
+            # ```
+            f.write(
+                f"::: {module.__name__}.{name}\n"
+                f"    options:\n"
+                f"      heading_level: 3\n"
+                f"      show_if_no_docstring: true\n"
+            )
+
+            f.write("\n")
+
+
+def gen_reference_extension_urls():
+    """
+    Generate documentation for the objects related to defining extension URLs.
+    """
+    module = import_module("django_components")
+
+    preface = "<!-- Autogenerated by reference.py -->\n\n"
+    preface += (root / "docs/templates/reference_extension_urls.md").read_text()
+    out_file = root / "docs/reference/extension_urls.md"
+
+    out_file.parent.mkdir(parents=True, exist_ok=True)
+    with out_file.open("w", encoding="utf-8") as f:
+        # 1. Insert section from `reference_extension_urls.md`
+        f.write(preface + "\n\n")
+
+        # 2. Print the context objects for each hook
+        main_module = import_module("django_components")
+        for name, obj in inspect.getmembers(main_module):
+            if not _is_extension_url_api(obj):
+                continue
+
+            # For each entry, generate a mkdocstrings entry, e.g.
+            # ```
+            # ::: django_components.util.routing.URLRoute
+            #     options:
+            #       show_if_no_docstring: true
+            # ```
+            f.write(
+                f"::: {module.__name__}.{name}\n"
+                f"    options:\n"
+                f"      heading_level: 3\n"
+                f"      show_if_no_docstring: true\n"
+            )
+
+            f.write("\n")
+
 
 forward_ref_pattern = re.compile(r"ForwardRef\('(.+?)'\)")
 class_repr_pattern = re.compile(r"<class '(.+?)'>")
@@ -1018,6 +1119,18 @@ def _is_template_tag(obj: Any) -> bool:
     return inspect.isclass(obj) and issubclass(obj, BaseNode)
 
 
+def _is_extension_hook_api(obj: Any) -> bool:
+    return inspect.isclass(obj) and getattr(obj, "_extension_hook_api", False)
+
+
+def _is_extension_command_api(obj: Any) -> bool:
+    return inspect.isclass(obj) and getattr(obj, "_extension_command_api", False)
+
+
+def _is_extension_url_api(obj: Any) -> bool:
+    return inspect.isclass(obj) and getattr(obj, "_extension_url_api", False)
+
+
 def gen_reference():
     """The entrypoint to generate all the reference documentation."""
     gen_reference_api()
@@ -1033,6 +1146,8 @@ def gen_reference():
     gen_reference_signals()
     gen_reference_testing_api()
     gen_reference_extension_hooks()
+    gen_reference_extension_commands()
+    gen_reference_extension_urls()
 
 
 # This is run when `gen-files` plugin is run in mkdocs.yml