refactor: fix some links, fix restart loop on file change of mkdocs serve (#1342)

docs/scripts/reference.py

@@ -44,6 +44,7 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Any, Dict, List, NamedTuple, Optional, Sequence, Tuple, Type, Union
 
+import mkdocs_gen_files
 from django.conf import settings
 from django.core.management.base import BaseCommand
 from django.urls import URLPattern, URLResolver
@@ -80,11 +81,11 @@ def gen_reference_api():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_api.md").read_text()
-    out_file = root / "docs/reference/api.md"
+    template_path = "docs/templates/reference_api.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/api.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -112,6 +113,8 @@ def gen_reference_api():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_testing_api():
     """
@@ -122,11 +125,11 @@ def gen_reference_testing_api():
     module = import_module("django_components.testing")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_testing_api.md").read_text()
-    out_file = root / "docs/reference/testing_api.md"
+    template_path = "docs/templates/reference_testing_api.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/testing_api.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -143,6 +146,8 @@ def gen_reference_testing_api():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_exceptions():
     """
@@ -151,11 +156,11 @@ def gen_reference_exceptions():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_exceptions.md").read_text()
-    out_file = root / "docs/reference/exceptions.md"
+    template_path = "docs/templates/reference_exceptions.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/exceptions.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -177,6 +182,8 @@ def gen_reference_exceptions():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_components():
     """
@@ -186,11 +193,11 @@ def gen_reference_components():
     module = import_module("django_components.components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_components.md").read_text()
-    out_file = root / "docs/reference/components.md"
+    template_path = "docs/templates/reference_components.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/components.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -234,6 +241,8 @@ def gen_reference_components():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_settings():
     """
@@ -242,11 +251,11 @@ def gen_reference_settings():
     module = import_module("django_components.app_settings")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_settings.md").read_text()
-    out_file = root / "docs/reference/settings.md"
+    template_path = "docs/templates/reference_settings.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/settings.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         # 1. Insert section from `reference_settings.md`
         f.write(preface + "\n\n")
 
@@ -288,6 +297,8 @@ def gen_reference_settings():
             )
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 # Get attributes / methods that are unique to the subclass
 def _get_unique_methods(base_class: Type, sub_class: Type):
@@ -347,8 +358,9 @@ def gen_reference_tagformatters():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_tagformatters.md").read_text()
-    out_file = root / "docs/reference/tag_formatters.md"
+    template_path = "docs/templates/reference_tagformatters.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/tag_formatters.md"
 
     tag_formatter_classes: Dict[str, Type[TagFormatterABC]] = {}
     tag_formatter_instances: Dict[str, TagFormatterABC] = {}
@@ -358,8 +370,7 @@ def gen_reference_tagformatters():
         elif _is_tag_formatter_cls(obj):
             tag_formatter_classes[name] = obj
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         # Generate a summary of available tag formatters.
@@ -402,6 +413,8 @@ def gen_reference_tagformatters():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_urls():
     """
@@ -410,13 +423,13 @@ def gen_reference_urls():
     module = import_module("django_components.urls")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_urls.md").read_text()
-    out_file = root / "docs/reference/urls.md"
+    template_path = "docs/templates/reference_urls.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/urls.md"
 
     all_urls = _list_urls(module.urlpatterns)
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         # Simply list all URLs, e.g.
@@ -431,11 +444,11 @@ def gen_reference_commands():
     These are discovered by looking at the files defined inside `management/commands`.
     """
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_commands.md").read_text()
-    out_file = root / "docs/reference/commands.md"
+    template_path = "docs/templates/reference_commands.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/commands.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         # Document all commands defined by django-components
@@ -530,6 +543,8 @@ def gen_reference_commands():
                 f"{cmd_desc}\n\n"
             )
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_template_tags():
     """
@@ -544,11 +559,11 @@ def gen_reference_template_tags():
     ]
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_template_tags.md").read_text()
-    out_file = root / "docs/reference/template_tags.md"
+    template_path = "docs/templates/reference_template_tags.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/template_tags.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for mod_name, mod_path in tags_modules:
@@ -591,6 +606,8 @@ def gen_reference_template_tags():
                     f"{docstring}\n\n"
                 )
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_template_variables():
     """
@@ -598,16 +615,18 @@ def gen_reference_template_variables():
     under the `{{ component_vars }}` variable, as defined by `ComponentVars`.
     """
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_template_variables.md").read_text()
-    out_file = root / "docs/reference/template_variables.md"
+    template_path = "docs/templates/reference_template_variables.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/template_variables.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for field in ComponentVars._fields:
             f.write(f"::: {ComponentVars.__module__}.{ComponentVars.__name__}.{field}\n\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_extension_hooks():
     """
@@ -616,11 +635,11 @@ def gen_reference_extension_hooks():
     module = import_module("django_components.extension")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_extension_hooks.md").read_text()
-    out_file = root / "docs/reference/extension_hooks.md"
+    template_path = "docs/templates/reference_extension_hooks.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/extension_hooks.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         # 1. Insert section from `reference_extension_hooks.md`
         f.write(preface + "\n\n")
 
@@ -700,6 +719,8 @@ def gen_reference_extension_hooks():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_extension_commands():
     """
@@ -708,11 +729,11 @@ def gen_reference_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"
+    template_path = "docs/templates/reference_extension_commands.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/extension_commands.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         # 1. Insert section from `reference_extension_commands.md`
         f.write(preface + "\n\n")
 
@@ -737,6 +758,8 @@ def gen_reference_extension_commands():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def gen_reference_extension_urls():
     """
@@ -745,11 +768,11 @@ def gen_reference_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"
+    template_path = "docs/templates/reference_extension_urls.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/extension_urls.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         # 1. Insert section from `reference_extension_urls.md`
         f.write(preface + "\n\n")
 
@@ -774,6 +797,8 @@ def gen_reference_extension_urls():
 
             f.write("\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 forward_ref_pattern = re.compile(r"ForwardRef\('(.+?)'\)")
 class_repr_pattern = re.compile(r"<class '(.+?)'>")
@@ -890,13 +915,15 @@ def gen_reference_signals():
     send by or during the use of django-components.
     """
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "docs/templates/reference_signals.md").read_text()
-    out_file = root / "docs/reference/signals.md"
+    template_path = "docs/templates/reference_signals.md"
+    preface += (root / template_path).read_text()
+    out_path = "reference/signals.md"
 
-    out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w", encoding="utf-8") as f:
+    with mkdocs_gen_files.open(out_path, "w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
+    mkdocs_gen_files.set_edit_path(out_path, template_path)
+
 
 def _list_urls(urlpatterns: Sequence[Union[URLPattern, URLResolver]], prefix=""):
     """Recursively extract all URLs and their associated views from Django's urlpatterns"""
@@ -1130,4 +1157,5 @@ def gen_reference():
 
 
 # This is run when `gen-files` plugin is run in mkdocs.yml
-gen_reference()
+if __name__ == "__main__":
+    gen_reference()