drf-to-mkdoc 0.1.5__tar.gz → 0.1.8__tar.gz

drf_to_mkdoc-0.1.8/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.4
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+  

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.1.5
+Version: 0.1.8
 Summary: Generate Markdown API docs from Django/DRF OpenAPI schema for MkDocs
 Author-email: Hossein Shayesteh <shayestehhs1@gmail.com>
 Maintainer-email: Hossein Shayesteh <shayestehhs1@gmail.com>
@@ -101,30 +101,8 @@ DRF_TO_MKDOC = {
 }
 ```
 
-2. **Create MkDocs configuration**:
-
-```yaml
-# mkdocs.yml
-site_name: Your API Documentation
-theme:
-  name: material
-  features:
-    - navigation.tabs
-    - navigation.sections
-    - navigation.expand
-    - search.highlight
-    - search.share
-
-plugins:
-  - search
-
-nav:
-  - Home: index.md
-  - About: about.md
-  - Models: models/index.md
-  - API Endpoints: endpoints/index.md
-  - Pagination: pagination.md
-```
+2. **Create MkDocs configuration**:  
+   Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.
 
 3. **Build documentation**:
 

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/README.md

@@ -52,30 +52,8 @@ DRF_TO_MKDOC = {
 }
 ```
 
-2. **Create MkDocs configuration**:
-
-```yaml
-# mkdocs.yml
-site_name: Your API Documentation
-theme:
-  name: material
-  features:
-    - navigation.tabs
-    - navigation.sections
-    - navigation.expand
-    - search.highlight
-    - search.share
-
-plugins:
-  - search
-
-nav:
-  - Home: index.md
-  - About: about.md
-  - Models: models/index.md
-  - API Endpoints: endpoints/index.md
-  - Pagination: pagination.md
-```
+2. **Create MkDocs configuration**:  
+   Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.
 
 3. **Build documentation**:
 

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/conf/defaults.py

@@ -7,4 +7,5 @@ DEFAULTS = {
     },
     "INDEX_TEMPLATE": "index.md",
     "AUTH_TEMPLATE": "auth.md",
+    "PATH_PARAM_SUBSTITUTOR": None,
 }

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/conf/settings.py

@@ -1,6 +1,8 @@
 from django.conf import settings
+
 from .defaults import DEFAULTS
 
+
 class DocBuilderSettings:
     def __init__(self, user_settings_key="DOC_BUILDER", defaults=None):
         self.user_settings_key = user_settings_key
@@ -15,4 +17,5 @@ class DocBuilderSettings:
     def __getattr__(self, key):
         return self.get(key)
 
+
 drf_to_mkdoc_settings = DocBuilderSettings(defaults=DEFAULTS)

drf_to_mkdoc-0.1.8/docs/mkdocs.yml

@@ -0,0 +1,70 @@
+site_name: API Documentation
+site_description: Comprehensive API documentation
+site_url: https://example.com/docs/
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.indexes
+    - toc.integrate
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.code.annotate
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Models: models/
+  - API Endpoints: endpoints/
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/ShayestehHS/drf-to-mkdoc/
+  generator: false
+
+copyright: Copyright © 2025 drf-to-mkdoc Project

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/__init__.py

@@ -4,4 +4,4 @@ DRF to MkDocs - Generate Markdown API docs from Django/DRF OpenAPI schema for Mk
 
 __version__ = "0.1.0"
 __author__ = "ShayestehHs"
-__email__ = "shayestehhs1@gmail.com"
+__email__ = "shayestehhs1@gmail.com"

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/apps.py

@@ -1,15 +1,19 @@
+import logging
+
 from django.apps import AppConfig
 
+logger = logging.getLogger()
+
 
 class DrfToMkdocConfig(AppConfig):
     default_auto_field = "django.db.models.BigAutoField"
     name = "drf_to_mkdoc"
     verbose_name = "DRF to MkDocs Documentation Generator"
-    
+
     def ready(self):
         """Initialize the app when Django starts."""
         # Import management commands to register them
         try:
             import drf_to_mkdoc.management.commands  # noqa
         except ImportError:
-            pass 
+            logger.exception("Failed to import drf_to_mkdoc commands")

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/conf/defaults.py

@@ -5,7 +5,6 @@ DEFAULTS = {
     "MODEL_DOCS_FILE": "docs/model-docs.json",  # Path to model documentation JSON file
     "DOC_CONFIG_FILE": "docs/configs/doc_config.json",  # Path to documentation configuration file
     "CUSTOM_SCHEMA_FILE": "docs/configs/custom_schema.json",  # Path to custom schema file
-
     # Django apps - required, no default
     "DJANGO_APPS": None,  # List of Django app names to process
 }

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/conf/settings.py

@@ -1,8 +1,11 @@
 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"}
 
     def __init__(self, user_settings_key="DRF_TO_MKDOC", defaults=None):
         self.user_settings_key = user_settings_key
@@ -11,16 +14,18 @@ class DRFToMkDocSettings:
 
     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}'")
-        
+
         value = self._user_settings.get(key, self.defaults[key])
-        
+
         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}."
             )
-        
+
         return value
 
     def __getattr__(self, key):
@@ -28,17 +33,18 @@ class DRFToMkDocSettings:
 
     def validate_required_settings(self):
         missing_settings = []
-        
+
         for setting in self.required_settings:
             try:
                 self.get(setting)
             except ValueError:
                 missing_settings.append(setting)
-        
+
         if missing_settings:
             raise ValueError(
                 f"Missing required settings: {', '.join(missing_settings)}. "
                 f"Please configure these in your Django settings under {self.user_settings_key}."
             )
 
+
 drf_to_mkdoc_settings = DRFToMkDocSettings(defaults=DEFAULTS)

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/management/commands/build_docs.py

@@ -1,11 +1,13 @@
+import shutil
 import subprocess
 from pathlib import Path
 
+from django.apps import apps
 from django.conf import settings
+from django.core.management import call_command
 from django.core.management.base import BaseCommand, CommandError
-from django.apps import apps
+
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from django.core.management import call_command
 
 
 class Command(BaseCommand):
@@ -18,13 +20,13 @@ class Command(BaseCommand):
         try:
             apps.check_apps_ready()
         except Exception as e:
-            raise CommandError(f"Django apps not properly configured: {e}")
+            raise CommandError(f"Django apps not properly configured: {e}") from e
 
         base_dir = Path(settings.BASE_DIR)
         site_dir = base_dir / "site"
         mkdocs_config = base_dir / "mkdocs.yml"
         mkdocs_config_alt = base_dir / "mkdocs.yaml"
-        
+
         if not mkdocs_config.exists() and not mkdocs_config_alt.exists():
             raise CommandError(
                 "MkDocs configuration file not found. Please create either 'mkdocs.yml' or 'mkdocs.yaml' "
@@ -34,10 +36,7 @@ class Command(BaseCommand):
         try:
             # Generate the model documentation JSON first
             self.stdout.write("Generating model documentation...")
-
-            call_command(
-                "generate_model_docs", "--pretty"
-            )
+            call_command("generate_model_docs", "--pretty")
             self.stdout.write(self.style.SUCCESS("Model documentation generated."))
 
             # Generate the documentation content
@@ -47,17 +46,7 @@ class Command(BaseCommand):
 
             # Build the MkDocs site
             self.stdout.write("Building MkDocs site...")
-            result = subprocess.run(
-                ["mkdocs", "build", "--clean"],
-                check=False,
-                cwd=base_dir,
-                capture_output=True,
-                text=True,
-            )
-
-            if result.returncode != 0:
-                raise CommandError(f"MkDocs build failed: {result.stderr}")
-
+            self._build_mkdocs_site(base_dir, site_dir)
             self.stdout.write(self.style.SUCCESS("Documentation built successfully!"))
             self.stdout.write(f"Site built in: {site_dir}")
 
@@ -65,3 +54,56 @@ class Command(BaseCommand):
             raise CommandError(
                 "MkDocs not found. Please install it with: pip install mkdocs mkdocs-material"
             ) from e
+
+    def _build_mkdocs_site(self, base_dir: Path, site_dir: Path) -> None:
+        """
+        Build the MkDocs site with proper security checks.
+
+        Args:
+            base_dir: The base directory of the Django project
+            site_dir: The directory where the site will be built
+
+        Raises:
+            FileNotFoundError: If mkdocs executable is not found
+            CommandError: If the build process fails
+        """
+        mkdocs_path = shutil.which("mkdocs")
+        if not mkdocs_path:
+            raise FileNotFoundError("mkdocs executable not found in PATH")
+
+        mkdocs_path_obj = Path(mkdocs_path)
+        if not mkdocs_path_obj.exists() or not mkdocs_path_obj.is_file():
+            raise CommandError(f"Invalid mkdocs executable path: {mkdocs_path}")
+
+        if not base_dir.is_absolute():
+            base_dir = base_dir.resolve()
+
+        if not base_dir.exists():
+            raise CommandError(f"Base directory does not exist: {base_dir}")
+
+        cmd = [
+            str(mkdocs_path_obj),  # Convert to string for subprocess
+            "build",
+            "--clean",
+        ]
+
+        try:
+            result = subprocess.run(  # noqa S603
+                cmd,
+                check=True,
+                cwd=str(base_dir),
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+
+            if result.stdout:
+                self.stdout.write(f"MkDocs output: {result.stdout}")
+
+        except subprocess.TimeoutExpired as e:
+            raise CommandError("MkDocs build timed out after 5 minutes") from e
+        except subprocess.CalledProcessError as e:
+            error_msg = f"MkDocs build failed (exit code {e.returncode})"
+            if e.stderr:
+                error_msg += f": {e.stderr}"
+            raise CommandError(error_msg) from e

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/management/commands/generate_docs.py

@@ -4,15 +4,15 @@ 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.common import get_schema, load_model_json_data
-from drf_to_mkdoc.utils.endpoint_generator import (
-    create_endpoints_index,
+from drf_to_mkdoc.utils.endpoint_detail_generator import (
     generate_endpoint_files,
     parse_endpoints_from_schema,
 )
-from drf_to_mkdoc.utils.model_generator import create_models_index, generate_model_docs
-from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-
+from drf_to_mkdoc.utils.endpoint_list_generator import create_endpoints_index
+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):

{drf_to_mkdoc-0.1.5 → drf_to_mkdoc-0.1.8}/drf_to_mkdoc/management/commands/generate_model_docs.py

@@ -9,6 +9,7 @@ from django.db import models
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
 
+
 class Command(BaseCommand):
     help = "Generate model documentation JSON from Django model introspection"
 
@@ -139,21 +140,50 @@ class Command(BaseCommand):
 
     def introspect_relationship(self, field):
         """Introspect relationship fields"""
-        return {
+        # Safely resolve related model label; can be None for generic relations
+        related_model_label = None
+        try:
+            if getattr(field, "related_model", None) is not None:
+                related_model_label = (
+                    f"{field.related_model._meta.app_label}.{field.related_model.__name__}"
+                )
+        except Exception:
+            related_model_label = None
+
+        relationship_data = {
             "name": field.name,
             "type": field.__class__.__name__,
-            "related_model": f"{field.related_model._meta.app_label}."
-            f"{field.related_model.__name__}",
+            "related_model": related_model_label,
             "related_name": getattr(field, "related_name", None),
             "on_delete": self.get_on_delete_name(field),
             "null": getattr(field, "null", False),
             "blank": getattr(field, "blank", False),
-            "many_to_many": field.many_to_many,
-            "one_to_many": field.one_to_many,
-            "many_to_one": field.many_to_one,
-            "one_to_one": field.one_to_one,
+            "many_to_many": getattr(field, "many_to_many", False),
+            "one_to_many": getattr(field, "one_to_many", False),
+            "many_to_one": getattr(field, "many_to_one", False),
+            "one_to_one": getattr(field, "one_to_one", False),
         }
 
+        # Handle Django generic relations where related_model can be None
+        field_class_name = field.__class__.__name__
+        if field_class_name in ("GenericForeignKey", "GenericRelation"):
+            relationship_data["is_generic"] = True
+            # Capture common generic relation details when available
+            for attr_name in (
+                "ct_field",
+                "fk_field",
+                "object_id_field",
+                "content_type_field",
+                "for_concrete_model",
+                "related_query_name",
+            ):
+                if hasattr(field, attr_name):
+                    relationship_data[attr_name] = getattr(field, attr_name)
+        else:
+            relationship_data["is_generic"] = False
+
+        return relationship_data
+
     def get_on_delete_name(self, field):
         """Get readable name for on_delete option"""
         if not hasattr(field, "on_delete") or field.on_delete is None:

drf_to_mkdoc-0.1.8/drf_to_mkdoc/static/drf-to-mkdoc/stylesheets/endpoints/base.css

@@ -0,0 +1,84 @@
+/* ===== BASE STYLES ===== */
+* {
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    line-height: 1.6;
+    transition: background-color 0.3s ease, color 0.3s ease;
+    margin: 0;
+    padding: 0;
+    min-height: 100vh;
+}
+
+.md-nav__item--active > .md-nav__link {
+    font-weight: 600;
+}
+
+/* Admonition customizations */
+.admonition.note {
+    border-left-color: var(--md-primary-fg-color);
+}
+
+.admonition.tip {
+    border-left-color: #00c853;
+}
+
+.admonition.warning {
+    border-left-color: #ff9800;
+}
+
+.admonition.danger {
+    border-left-color: #f44336;
+}
+
+/* Search result enhancements */
+.md-search-result__meta {
+    color: var(--md-default-fg-color--light);
+}
+
+/* Code syntax highlighting enhancements */
+.codehilite .k { color: #0066cc; }  /* Keywords */
+.codehilite .s { color: #009900; }  /* Strings */
+.codehilite .c { color: #999999; }  /* Comments */
+.codehilite .n { color: #333333; }  /* Names */
+.codehilite .o { color: #666666; }  /* Operators */
+
+/* Custom icons for different sections */
+.md-nav__item[data-md-level="1"] > .md-nav__link[href*="models"] {
+    position: relative;
+}
+
+.md-nav__item[data-md-level="1"] > .md-nav__link[href*="models"]::before {
+    content: "🗃️";
+    margin-right: 0.5rem;
+}
+
+.md-nav__item[data-md-level="1"] > .md-nav__link[href*="endpoints"] {
+    position: relative;
+}
+
+.md-nav__item[data-md-level="1"] > .md-nav__link[href*="endpoints"]::before {
+    content: "🔗";
+    margin-right: 0.5rem;
+}
+
+/* Print styles */
+@media print {
+    .md-header, .md-sidebar, .md-footer {
+        display: none;
+    }
+
+    .md-content {
+        margin: 0;
+    }
+
+    .highlight pre {
+        border: 1px solid #ccc;
+        page-break-inside: avoid;
+    }
+}
+