fix: replace legacy python handler with new mkdocstrings-python handler

docs/gen_reference_nav.py

@@ -20,23 +20,30 @@
 nav = mkdocs_gen_files.Nav()  # type: ignore[no-untyped-call]
 
 for path in sorted(Path(CODE_ROOT).glob('**/*.py')):
+    module_path = path.relative_to('.').with_suffix('')
     doc_path = Path('reference', path.relative_to('.')).with_suffix('.md')
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == '__init__':
+        parts = parts[:-1]
+        doc_path = doc_path.with_name('index.md')
+
     # fully qualified name
-    ident = '.'.join(path.relative_to('.').with_suffix('').parts)
+    ident = '.'.join(parts)
 
     # skip database migrations
-    if '.migrations' in ident:
+    if 'migrations' in parts:
         continue
 
     # add mapping from Python file name to generated Markdown page
     # the path needs to be relative to the SUMMARY.md file
     # i.e., without "reference/" prefix if the index is in the same directory
-    parts = tuple(path.parts)
-    nav[parts] = str(path.relative_to('.').with_suffix('.md'))
+    nav[parts] = doc_path.relative_to('reference').as_posix()
 
     # write Markdown file for module
     with mkdocs_gen_files.open(doc_path, 'w') as fd:
-        print(f'::: {ident}', file=fd)
+        fd.write(f'::: {ident}\n')
 
     mkdocs_gen_files.set_edit_path(doc_path, Path('..', path))
 

mkdocs.yml

@@ -76,24 +76,13 @@ plugins:
   - gen-files:
       scripts:
         - docs/gen_reference_nav.py
-  # # auto-generate navigation structure for code reference
+  # auto-generate navigation structure for code reference
   - literate-nav:
       nav_file: SUMMARY.md
   - mkdocstrings:
-      default_handler: python
       handlers:
         python:
-          setup_commands:
-            - import os
-            - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.development")
-            - import django
-            - django.setup()
-            # mock pytkdocs to workaround Django and Django REST framework issues
-            - import docs.mock_django
-          options:
-            # filter out Pydantic internal attributes
-            filters: ['!^__']
-          import:
+          inventories:
             # import Sphinx objects inventories to support referencing other elements in docs
             - https://docs.python.org/3/objects.inv
             - https://docs.djangoproject.com/en/dev/_objects/

pyproject.toml

@@ -91,7 +91,8 @@ docs = [
     "mkdocs-gen-files==0.6.0",
     "mkdocs-literate-nav==0.6.2",
     "mkdocs-material==9.7.6",
-    "mkdocstrings[python-legacy]==1.0.4",
+    "mkdocstrings==1.0.4",
+    "mkdocstrings-python==2.0.3",
 ]
 
 [tool.uv]