drf-to-mkdoc 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

drf_to_mkdoc/conf/defaults.py

@@ -7,6 +7,11 @@ DEFAULTS = {
     "CUSTOM_SCHEMA_FILE": "docs/configs/custom_schema.json",  # Path to custom schema file
     "PATH_PARAM_SUBSTITUTE_FUNCTION": None,
     "PATH_PARAM_SUBSTITUTE_MAPPING": {},
+    # AI documentation settings
+    "ENABLE_AI_DOCS": False,
+    "AI_CONFIG_DIR_NAME": "ai_code",  # Directory name for AI-generated code files
+    "AI_OPERATION_MAP_FILE": "docs/configs/operation_map.json",  # Path to operation map file
+    "SERIALIZERS_INHERITANCE_DEPTH": 1,  # Maximum depth for class inheritance analysis
     # Django apps - required, no default
     "DJANGO_APPS": None,  # List of Django app names to process
 }

drf_to_mkdoc/conf/settings.py

@@ -1,31 +1,143 @@
+from pathlib import Path
+from typing import Any, ClassVar
+
 from django.conf import settings
 
 from drf_to_mkdoc.conf.defaults import DEFAULTS
 
 
 class DRFToMkDocSettings:
-    required_settings = ["DJANGO_APPS"]
-    project_settings = {"PROJECT_NAME": "drf-to-mkdoc"}
+    required_settings: ClassVar[list[str]] = ["DJANGO_APPS"]
+    project_settings: ClassVar[dict[str, Any]] = {"PROJECT_NAME": "drf-to-mkdoc"}
+
+    settings_types: ClassVar[dict[str, type]] = {
+        "ENABLE_AI_DOCS": bool,
+        "AI_CONFIG_DIR_NAME": str,
+        "SERIALIZERS_INHERITANCE_DEPTH": int,
+    }
+
+    settings_ranges: ClassVar[dict[str, tuple[int, int]]] = {
+        "SERIALIZERS_INHERITANCE_DEPTH": (1, 3),
+    }
+
+    path_settings = {
+        "CONFIG_DIR",
+        "MODEL_DOCS_FILE",
+        "DOC_CONFIG_FILE",
+        "CUSTOM_SCHEMA_FILE",
+        "AI_OPERATION_MAP_FILE",
+    }
 
     def __init__(self, user_settings_key="DRF_TO_MKDOC", defaults=None):
         self.user_settings_key = user_settings_key
         self._user_settings = getattr(settings, user_settings_key, {})
         self.defaults = defaults or {}
 
-    def get(self, key):
-        if key not in self.defaults:
-            if key in self.project_settings:
-                return self.project_settings[key]
-            raise AttributeError(f"Invalid DRF_TO_MKDOC setting: '{key}'")
+    def _validate_type(self, key: str, value: Any) -> None:
+        """Validate the type of setting value."""
+        if key in self.settings_types:
+            expected_type = self.settings_types[key]
+            if not isinstance(value, expected_type):
+                raise TypeError(
+                    f"DRF_TO_MKDOC setting '{key}' must be of type {expected_type.__name__}, "
+                    f"got {type(value).__name__} instead."
+                )
 
-        value = self._user_settings.get(key, self.defaults[key])
+    def _validate_range(self, key: str, value: Any) -> None:
+        """Validate the range of a setting value."""
+        if key in self.settings_ranges:
+            min_val, max_val = self.settings_ranges[key]
+            if not min_val <= value <= max_val:
+                raise ValueError(
+                    f"DRF_TO_MKDOC setting '{key}' must be between {min_val} and {max_val}, "
+                    f"got {value} instead."
+                )
 
+    def _validate_required(self, key: str, value: Any) -> None:
+        """Validate if a required setting is configured."""
         if value is None and key in self.required_settings:
             raise ValueError(
                 f"DRF_TO_MKDOC setting '{key}' is required but not configured. "
                 f"Please add it to your Django settings under {self.user_settings_key}."
             )
 
+    def _validate_dir(self, key: str, value: str) -> None:
+        if key not in self.path_settings or not isinstance(value, str):
+            return
+
+        if not value.strip():
+            raise ValueError(
+                f"DRF_TO_MKDOC path setting '{key}' cannot be empty or contain only whitespace."
+            )
+
+        dangerous_components = {"..", "~", "/", "\\"}
+        path_parts = Path(value).parts
+        for part in path_parts:
+            if part in dangerous_components or part.startswith("."):
+                raise ValueError(
+                    f"DRF_TO_MKDOC path setting '{key}' contains unsafe path component '{part}'. "
+                    f"Directory names should be simple names without separators or relative path components."
+                )
+
+        if Path(value).is_absolute():
+            raise ValueError(
+                f"DRF_TO_MKDOC path setting '{key}' cannot be an absolute path. "
+                f"Use relative directory names only."
+            )
+
+        reserved_names = {
+            "CON",
+            "PRN",
+            "AUX",
+            "NUL",
+            "COM1",
+            "COM2",
+            "COM3",
+            "COM4",
+            "COM5",
+            "COM6",
+            "COM7",
+            "COM8",
+            "COM9",
+            "LPT1",
+            "LPT2",
+            "LPT3",
+            "LPT4",
+            "LPT5",
+            "LPT6",
+            "LPT7",
+            "LPT8",
+            "LPT9",
+        }
+        if value.upper() in reserved_names:
+            raise ValueError(
+                f"DRF_TO_MKDOC path setting '{key}' uses a reserved system name '{value}'. "
+                f"Please choose a different name."
+            )
+
+        invalid_chars = '<>:"|?*'
+        if any(char in value for char in invalid_chars):
+            raise ValueError(
+                f"DRF_TO_MKDOC path setting '{key}' contains invalid characters. "
+                f"Avoid using: {invalid_chars}"
+            )
+
+    def get(self, key):
+        if key in self.project_settings:
+            return self.project_settings[key]
+
+        # User-provided settings take precedence
+        if key in self._user_settings:
+            value = self._user_settings[key]
+        else:
+            value = self.defaults.get(key, None)
+
+        # Run all validations
+        self._validate_required(key, value)
+        self._validate_type(key, value)
+        self._validate_range(key, value)
+        self._validate_dir(key, value)
+
         return value
 
     def __getattr__(self, key):
@@ -37,7 +149,7 @@ class DRFToMkDocSettings:
         for setting in self.required_settings:
             try:
                 self.get(setting)
-            except ValueError:
+            except (ValueError, AttributeError):
                 missing_settings.append(setting)
 
         if missing_settings:

drf_to_mkdoc/management/commands/build_docs.py

@@ -34,15 +34,16 @@ class Command(BaseCommand):
             )
 
         try:
-            # Generate the model documentation JSON first
-            self.stdout.write("Generating model documentation...")
-            call_command("generate_model_docs", "--pretty")
-            self.stdout.write(self.style.SUCCESS("Model documentation generated."))
+            # Extract model data from Django models
+            self.stdout.write("Extracting model data...")
+            call_command("extract_model_data", "--pretty")
+            self.stdout.write(self.style.SUCCESS("Model data extracted."))
 
             # Generate the documentation content
-            self.stdout.write("Generating documentation content...")
-            call_command("generate_docs")
-            self.stdout.write(self.style.SUCCESS("Documentation content generated."))
+            self.stdout.write("Building documentation content...")
+            call_command("build_model_docs")
+            call_command("build_endpoint_docs")
+            self.stdout.write(self.style.SUCCESS("Documentation content built."))
 
             # Build the MkDocs site
             self.stdout.write("Building MkDocs site...")

drf_to_mkdoc/management/commands/build_endpoint_docs.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+
+from django.core.management.base import BaseCommand
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.commons.schema_utils import get_schema
+from drf_to_mkdoc.utils.endpoint_detail_generator import (
+    generate_endpoint_files,
+    parse_endpoints_from_schema,
+)
+from drf_to_mkdoc.utils.endpoint_list_generator import create_endpoints_index
+
+
+class Command(BaseCommand):
+    help = "Build endpoint documentation from OpenAPI schema"
+
+    def handle(self, *args, **options):
+        self.stdout.write(
+            self.style.SUCCESS("🚀 Starting endpoint documentation generation...")
+        )
+
+        docs_dir = self._setup_docs_directory()
+        schema_data = self._load_schema_data()
+
+        if schema_data:
+            self._generate_endpoints_documentation(schema_data, docs_dir)
+            self.stdout.write(
+                self.style.SUCCESS("✅ Endpoint documentation generation complete!")
+            )
+        else:
+            self.stdout.write(self.style.ERROR("❌ Failed to generate endpoint documentation."))
+
+    def _setup_docs_directory(self):
+        docs_dir = Path(drf_to_mkdoc_settings.DOCS_DIR)
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        return docs_dir
+
+    def _load_schema_data(self):
+        try:
+            schema = get_schema()
+        except Exception as e:
+            self.stdout.write(self.style.ERROR(f"❌ Failed to load OpenAPI schema: {e}"))
+            return {}
+        if not schema:
+            self.stdout.write(self.style.ERROR("❌ Failed to load OpenAPI schema"))
+            return {}
+
+        paths = schema.get("paths", {})
+        components = schema.get("components", {})
+
+        self.stdout.write(f"📊 Loaded {len(paths)} API paths")
+
+        return {"paths": paths, "components": components}
+
+    def _generate_endpoints_documentation(self, schema_data, docs_dir):
+        self.stdout.write("🔗 Generating endpoint documentation...")
+
+        paths = schema_data["paths"]
+        components = schema_data["components"]
+
+        endpoints_by_app = parse_endpoints_from_schema(paths)
+        total_endpoints = generate_endpoint_files(endpoints_by_app, components)
+        create_endpoints_index(endpoints_by_app, docs_dir)
+
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"✅ Generated {total_endpoints} endpoint files with Django view introspection"
+            )
+        )

drf_to_mkdoc/management/commands/build_model_docs.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+from django.core.management.base import BaseCommand
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.commons.file_utils import load_json_data
+from drf_to_mkdoc.utils.model_detail_generator import generate_model_docs
+from drf_to_mkdoc.utils.model_list_generator import create_models_index
+
+
+class Command(BaseCommand):
+    help = "Build model documentation from model JSON data"
+
+    def handle(self, *args, **options):
+        self.stdout.write(self.style.SUCCESS("🚀 Starting model documentation generation..."))
+
+        docs_dir = self._setup_docs_directory()
+        models_data = self._load_models_data()
+
+        if models_data:
+            self._generate_models_documentation(models_data, docs_dir)
+            self.stdout.write(self.style.SUCCESS("✅ Model documentation generation complete!"))
+        else:
+            self.stdout.write(self.style.ERROR("❌ Failed to generate model documentation."))
+
+    def _setup_docs_directory(self):
+        docs_dir = Path(drf_to_mkdoc_settings.DOCS_DIR)
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        return docs_dir
+
+    def _load_models_data(self):
+        models_data = load_json_data(
+            drf_to_mkdoc_settings.MODEL_DOCS_FILE, raise_not_found=False
+        )
+
+        if not models_data:
+            self.stdout.write(self.style.WARNING("⚠️  No model data found"))
+
+        return models_data
+
+    def _generate_models_documentation(self, models_data, docs_dir):
+        self.stdout.write("📋 Generating model documentation...")
+
+        try:
+            generate_model_docs(models_data)
+            create_models_index(models_data, docs_dir)
+            self.stdout.write(self.style.SUCCESS("✅ Model documentation generated"))
+        except Exception as e:
+            self.stdout.write(self.style.WARNING(f"⚠️  Failed to generate model docs: {e}"))
+            raise

drf_to_mkdoc/management/commands/{generate_model_docs.py → extract_model_data.py}

@@ -1,6 +1,7 @@
 import inspect
 import json
 import re
+from collections import defaultdict
 from pathlib import Path
 
 from django.apps import apps
@@ -11,7 +12,7 @@ from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
 
 
 class Command(BaseCommand):
-    help = "Generate model documentation JSON from Django model introspection"
+    help = "Extract model data from Django model introspection and save as JSON"
 
     def add_arguments(self, parser):
         parser.add_argument(
@@ -38,33 +39,26 @@ class Command(BaseCommand):
 
         model_docs = self.generate_model_documentation(exclude_apps)
 
-        json_data = {
-            "models": model_docs,
-            "stats": {
-                "total_models": len(model_docs),
-                "total_apps": len({model["app_label"] for model in model_docs.values()}),
-            },
-        }
-
         output_path = Path(output_file)
         output_path.parent.mkdir(parents=True, exist_ok=True)
         with output_path.open("w", encoding="utf-8") as f:
+            payload = dict(model_docs)
             if pretty:
-                json.dump(json_data, f, indent=2, ensure_ascii=False, default=str)
+                json.dump(payload, f, ensure_ascii=False, sort_keys=True, default=str, indent=2)
             else:
-                json.dump(json_data, f, ensure_ascii=False, default=str)
+                json.dump(payload, f, ensure_ascii=False, sort_keys=True, default=str)
 
         self.stdout.write(
             self.style.SUCCESS(f"✅ Generated model documentation: {output_path.absolute()}")
         )
-        self.stdout.write(f"📊 Total models: {len(model_docs)}")
         self.stdout.write(
-            f"📦 Total apps: {len({model['app_label'] for model in model_docs.values()})}"
+            f"📊 Total models: {sum([len(model_docs[app_label]) for app_label in model_docs])}"
         )
+        self.stdout.write(f"📦 Total apps: {len(model_docs)}")
 
     def generate_model_documentation(self, exclude_apps):
         """Generate documentation for all Django models"""
-        model_docs = {}
+        model_docs = defaultdict(dict)
 
         for app_config in apps.get_app_configs():
             app_label = app_config.label
@@ -78,13 +72,11 @@ class Command(BaseCommand):
 
             for model in app_config.get_models():
                 model_name = model.__name__
-                model_key = f"{app_label}.{model_name}"
-
                 self.stdout.write(f"  📋 Processing model: {model_name}")
 
-                model_docs[model_key] = self.introspect_model(model, app_label)
+                model_docs[app_label][model_name] = self.introspect_model(model, app_label)
 
-        return model_docs
+        return {app_label: dict(models) for app_label, models in model_docs.items()}
 
     def introspect_model(self, model, app_label):
         """Introspect a single Django model"""
@@ -154,6 +146,9 @@ class Command(BaseCommand):
             "type": field.__class__.__name__,
             "related_model": related_model_label,
             "related_name": getattr(field, "related_name", None),
+            "app_label": field.related_model._meta.app_label,
+            "table_name": field.related_model._meta.db_table,
+            "verbose_name": field.related_model._meta.verbose_name,
             "on_delete": self.get_on_delete_name(field),
             "null": getattr(field, "null", False),
             "blank": getattr(field, "blank", False),
@@ -286,7 +281,7 @@ class Command(BaseCommand):
                 if display_method_match:
                     field_name = display_method_match.group(1)
                     if field_name in model_field_names:
-                        # Exclude if the field doesn't exist in the model
+                        # Exclude built-in get_<field>_display for fields present on the model
                         continue
 
                 method = getattr(model, attr_name)

drf_to_mkdoc/templates/endpoints/detail/base.html

@@ -0,0 +1,33 @@
+<!-- inject CSS and JS directly -->
+{% load custom_filters %}
+{% for stylesheet in stylesheets %}
+<link rel="stylesheet" href="{% static_with_prefix stylesheet prefix_path %}">
+{% endfor %}
+{% for script in scripts %}
+<script src="{% static_with_prefix script prefix_path %}" defer></script>
+{% endfor %}
+
+# {{ method|upper }} {{ path }}
+
+{{ method|format_method_badge|safe }} `{{ path }}`
+
+**View class:** {{ viewset_name }}
+
+{% if summary %}
+## Overview
+
+{{ summary }}
+{% endif %}
+
+{% if operation_id %}
+**Operation ID:** `{{ operation_id }}`
+{% endif %}
+
+{% if description %}
+{{ description|safe }}
+{% endif %}
+
+{% include "endpoints/detail/path_parameters.html" %}
+{% include "endpoints/detail/query_parameters.html" %}
+{% include "endpoints/detail/request_body.html" %}
+{% include "endpoints/detail/responses.html" %}

drf_to_mkdoc/templates/endpoints/detail/path_parameters.html

@@ -0,0 +1,8 @@
+{% if path_params %}
+## Path Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+{% for param in path_params %}| `{{ param.name }}` | `{{ param.schema.type|default:"string" }}` | {{ param.required|yesno:"Yes,No" }} | {{ param.description }} |{% endfor %}
+{% endif %}
+

drf_to_mkdoc/templates/endpoints/detail/query_parameters.html

@@ -0,0 +1,43 @@
+{% comment %}
+Check if any query parameter fields have content
+{% endcomment %}
+
+{% if query_parameters.filter_fields or query_parameters.search_fields or query_parameters.ordering_fields or query_parameters.filter_backends or query_parameters.pagination_fields %}
+## Query Parameters
+
+{% if query_parameters.filter_fields %}
+### Filter Fields
+{% for field in query_parameters.filter_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.search_fields %}
+### Search Fields
+{% for field in query_parameters.search_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.ordering_fields %}
+### Ordering Fields
+{% for field in query_parameters.ordering_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.filter_backends %}
+### Filter Backends
+{% for backend in query_parameters.filter_backends %}
+- `{{ backend }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.pagination_fields %}
+### Pagination Fields
+{% for field in query_parameters.pagination_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% endif %}

drf_to_mkdoc/templates/endpoints/detail/request_body.html

@@ -0,0 +1,10 @@
+{% load custom_filters %}
+
+{% if request_body %}
+## Request Body
+
+{% if request_example %}
+{{ request_example|format_json }}
+{% endif %}
+
+{% endif %}

drf_to_mkdoc/templates/endpoints/detail/responses.html

@@ -0,0 +1,18 @@
+{% load custom_filters %}
+
+{% if responses %}
+## Responses
+
+{% for response in responses %}
+### {{ response.status_code }}
+
+{% if response.description %}
+{{ response.description }}
+{% endif %}
+
+{% if response.example %}
+{{ response.example|format_json }}
+{% endif %}
+
+{% endfor %}
+{% endif %}

drf_to_mkdoc/templates/endpoints/list/base.html

@@ -0,0 +1,23 @@
+# API Endpoints
+
+<style>
+{% for stylesheet in stylesheets %}
+@import url("{{ stylesheet|safe }}");
+{% endfor %}
+</style>
+
+{% for script in scripts %}
+<script src="{{ script|safe }}" defer></script>
+{% endfor %}
+
+<div class="main-content">
+    {% include "endpoints/list/filter_section.html" %}
+    {% for app_name, endpoints in endpoints_by_app.items %}
+        <h2>{{ app_name|title }}</h2>
+        <div class="endpoints-grid">
+            {% for endpoint in endpoints %}
+                {% include "endpoints/list/endpoint_card.html" %}
+            {% endfor %}
+        </div>
+    {% endfor %}
+</div>

drf_to_mkdoc/templates/endpoints/list/endpoint_card.html

@@ -0,0 +1,18 @@
+{% load custom_filters %}
+<a href="{{ endpoint.link_url }}" class="endpoint-card"
+    data-method="{{ endpoint.method|lower }}"
+    data-path="{{ endpoint.path|lower }}"
+    data-app="{{ app_name|lower }}"
+    data-auth="{{ endpoint.auth_required|default:'false'|lower }}"
+    data-pagination="{{ endpoint.pagination_support|default:'false'|lower }}"
+    data-search="{{ endpoint.view_class.search_fields|default:''|length|yesno:'true,false'|lower }}"
+    data-ordering="{{ endpoint.ordering_support|default:'false'|lower }}"
+    data-models="{{ endpoint.related_models|default:''|join:' '|lower }}"
+    data-roles="{{ endpoint.permission_roles|default:''|join:' '|lower }}"
+    data-content-type="{{ endpoint.content_type|default:''|lower }}"
+    data-tags="{{ endpoint.tags|default:''|join:' '|lower }}"
+    data-schema="{{ endpoint.schema_fields|default:''|join:' '|lower }}"
+    data-params="{{ endpoint.query_parameters|default:''|join:' '|lower }}">
+    <span class="method-badge method-{{ endpoint.method|lower }}">{{ endpoint.method }}</span>
+    <span class="endpoint-path">{{ endpoint.path }}</span>
+</a>

drf_to_mkdoc/templates/endpoints/list/filter_section.html

@@ -0,0 +1,16 @@
+<div class="filter-sidebar collapsed" id="filterSidebar">
+    <h3 class="filter-title">🔍 Filters</h3>
+    <div class="filter-grid">
+        {% for filter_key in active_filters %}
+            {% include "endpoints/list/filters/"|add:filter_key|add:".html" %}
+        {% endfor %}
+    </div>
+
+    <div class="filter-actions">
+        <button class="filter-apply" onclick="applyFilters()">Apply</button>
+        <button class="filter-clear" onclick="clearFilters()">Clear</button>
+    </div>
+
+    <div class="filter-results">Showing 0 endpoints</div>
+</div>
+

drf_to_mkdoc/templates/endpoints/list/filters/app.html

@@ -0,0 +1,8 @@
+<div class="filter-group">
+    <label class="filter-label">Django App</label>
+    <select id="filter-app" class="filter-select">
+        <option value="">All</option>
+        <!-- Dynamically filled -->
+    </select>
+</div>
+

drf_to_mkdoc/templates/endpoints/list/filters/method.html

@@ -0,0 +1,12 @@
+<div class="filter-group">
+    <label class="filter-label">HTTP Method</label>
+    <select id="filter-method" class="filter-select">
+        <option value="">All</option>
+        <option value="get">GET</option>
+        <option value="post">POST</option>
+        <option value="put">PUT</option>
+        <option value="patch">PATCH</option>
+        <option value="delete">DELETE</option>
+    </select>
+</div>
+

drf_to_mkdoc/templates/endpoints/list/filters/path.html

@@ -0,0 +1,5 @@
+<div class="filter-group">
+    <label class="filter-label">Endpoint Path</label>
+    <input type="text" id="filter-path" class="filter-input" placeholder="Search path...">
+</div>
+

drf_to_mkdoc/templates/endpoints/list/filters/search.html

@@ -0,0 +1,9 @@
+<div class="filter-group">
+    <label class="filter-label">Search Support</label>
+    <select id="filter-search" class="filter-select">
+        <option value="">All</option>
+        <option value="true">Yes</option>
+        <option value="false">No</option>
+    </select>
+</div>
+

drf_to_mkdoc/templates/model_detail/base.html

@@ -0,0 +1,34 @@
+# {{ name }}
+
+<!-- inject CSS directly -->
+{% for stylesheet in stylesheets %}
+<link rel="stylesheet" href="{{ stylesheet }}">
+{% endfor %}
+
+**App:** {{ app_label }}
+
+**Table:** `{{ table_name }}`
+
+## Description
+
+{{ description }}
+
+{% if fields %}
+{% include "model_detail/fields.html" with fields=fields %}
+{% endif %}
+
+{% if has_choices %}
+{% include "model_detail/choices.html" with fields=fields %}
+{% endif %}
+
+{% if relationships %}
+{% include "model_detail/relationships.html" with relationships=relationships %}
+{% endif %}
+
+{% if methods %}
+{% include "model_detail/methods.html" with methods=methods %}
+{% endif %}
+
+{% if meta_options %}
+{% include "model_detail/meta.html" with meta_options=meta_options %}
+{% endif %}