feat(backend): improve tag docs (#8960)

* add admindocs

* add tag export command

* add filter export

* switch to yaml

* upload meta info to artifacts

* format workflow file

* fix creation command

* keep all artifacts in schema repo

* fix namespace

* use one command for export

* include tags and filters in docs

* change default filename

* fix call

* fix itteration syntax

* clean up rendering

* fix formatting

* simple escape

src/backend/InvenTree/InvenTree/management/commands/export_filters.py

@@ -0,0 +1,58 @@
+"""Custom management command to export all filters.
+
+This is used to generate a YAML file which contains all of the filters available in InvenTree.
+"""
+
+from django.contrib.admindocs import utils
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management.base import BaseCommand
+from django.template.engine import Engine
+
+import yaml
+
+
+class Command(BaseCommand):
+    """Extract filter information, and export to a YAML file."""
+
+    def add_arguments(self, parser):
+        """Add custom arguments for this command."""
+        parser.add_argument(
+            'filename', type=str, help='Output filename for filter definitions'
+        )
+
+    def handle(self, *args, **kwargs):
+        """Export filter information to a YAML file."""
+        filters = discover_filters()
+        # Write
+        filename = kwargs.get('filename', 'inventree_filters.yml')
+        with open(filename, 'w', encoding='utf-8') as f:
+            yaml.dump(filters, f, indent=4)
+        print(f"Exported InvenTree filter definitions to '{filename}'")
+
+
+def discover_filters():
+    """Discover all available filters.
+
+    This function is a copy of a function from the Django 'admindocs' module in django.contrib.admindocs.views.TemplateFilterIndexView
+    """
+    filters = []
+    try:
+        engine = Engine.get_default()
+    except ImproperlyConfigured:
+        # Non-trivial TEMPLATES settings aren't supported (#24125).
+        pass
+    else:
+        app_libs = sorted(engine.template_libraries.items())
+        builtin_libs = [('', lib) for lib in engine.template_builtins]
+        for module_name, library in builtin_libs + app_libs:
+            for filter_name, filter_func in library.filters.items():
+                title, body, metadata = utils.parse_docstring(filter_func.__doc__)
+                tag_library = module_name.split('.')[-1]
+                filters.append({
+                    'name': filter_name,
+                    'title': title,
+                    'body': body,
+                    'meta': metadata,
+                    'library': tag_library,
+                })
+    return filters

src/backend/InvenTree/InvenTree/management/commands/export_tags.py

@@ -0,0 +1,59 @@
+"""Custom management command to export all tags.
+
+This is used to generate a YAML file which contains all of the tags available in InvenTree.
+"""
+
+from django.contrib.admindocs import utils
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management.base import BaseCommand
+from django.template.engine import Engine
+
+import yaml
+
+
+class Command(BaseCommand):
+    """Extract tag information, and export to a YAML file."""
+
+    def add_arguments(self, parser):
+        """Add custom arguments for this command."""
+        parser.add_argument(
+            'filename', type=str, help='Output filename for tag definitions'
+        )
+
+    def handle(self, *args, **kwargs):
+        """Export tag information to a YAML file."""
+        tags = discover_tags()
+
+        # Write
+        filename = kwargs.get('filename', 'inventree_tags.yml')
+        with open(filename, 'w', encoding='utf-8') as f:
+            yaml.dump(tags, f, indent=4)
+        print(f"Exported InvenTree tag definitions to '{filename}'")
+
+
+def discover_tags():
+    """Discover all available tags.
+
+    This function is a copy of a function from the Django 'admindocs' module in django.contrib.admindocs.views.TemplateTagIndexView
+    """
+    tags = []
+    try:
+        engine = Engine.get_default()
+    except ImproperlyConfigured:
+        # Non-trivial TEMPLATES settings aren't supported (#24125).
+        pass
+    else:
+        app_libs = sorted(engine.template_libraries.items())
+        builtin_libs = [('', lib) for lib in engine.template_builtins]
+        for module_name, library in builtin_libs + app_libs:
+            for tag_name, tag_func in library.tags.items():
+                title, body, metadata = utils.parse_docstring(tag_func.__doc__)
+                tag_library = module_name.split('.')[-1]
+                tags.append({
+                    'name': tag_name,
+                    'title': title,
+                    'body': body,
+                    'meta': metadata,
+                    'library': tag_library,
+                })
+    return tags

src/backend/InvenTree/InvenTree/settings.py

@@ -255,6 +255,7 @@ INVENTREE_ADMIN_URL = get_setting(
 INSTALLED_APPS = [
     # Admin site integration
     'django.contrib.admin',
+    'django.contrib.admindocs',
     # InvenTree apps
     'build.apps.BuildConfig',
     'common.apps.CommonConfig',

src/backend/InvenTree/InvenTree/urls.py

@@ -188,6 +188,7 @@ if settings.INVENTREE_ADMIN_ENABLED:
 
     urlpatterns += [
         path(f'{admin_url}/error_log/', include('error_report.urls')),
+        path(f'{admin_url}/doc/', include('django.contrib.admindocs.urls')),
         path(f'{admin_url}/', admin.site.urls, name='inventree-admin'),
     ]
 

src/backend/requirements.in

@@ -33,6 +33,7 @@ djangorestframework-simplejwt[crypto]   # JWT authentication
 django-xforwardedfor-middleware         # IP forwarding metadata
 dj-rest-auth==7.0.0                     # Authentication API endpoints # FIXED 2024-12-22 due to https://github.com/inventree/InvenTree/issues/8707
 dulwich                                 # pure Python git integration
+docutils                                # Documentation utilities for auto admin docs
 drf-spectacular                         # DRF API documentation
 feedparser                              # RSS newsfeed parser
 gunicorn                                # Gunicorn web server

src/backend/requirements.txt

@@ -546,6 +546,10 @@ djangorestframework-simplejwt[crypto]==5.4.0 \
     --hash=sha256:7aec953db9ed4163430c16d086eecb0f028f814ce6bba62b06c25919261e9077 \
     --hash=sha256:cccecce1a0e1a4a240fae80da73e5fc23055bababb8b67de88fa47cd36822320
     # via -r src/backend/requirements.in
+docutils==0.21.2 \
+    --hash=sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f \
+    --hash=sha256:dafca5b9e384f0e419294eb4d2ff9fa826435bf15f15b7bd45723e8ad76811b2
+    # via -r src/backend/requirements.in
 drf-spectacular==0.28.0 \
     --hash=sha256:2c778a47a40ab2f5078a7c42e82baba07397bb35b074ae4680721b2805943061 \
     --hash=sha256:856e7edf1056e49a4245e87a61e8da4baff46c83dbc25be1da2df77f354c7cb4