drf-to-mkdoc 0.1.6__tar.gz → 1.0.7__tar.gz

drf_to_mkdoc-1.0.7/.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.6 → drf_to_mkdoc-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.1.6
+Version: 1.0.7
 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>

{drf_to_mkdoc-0.1.6 → drf_to_mkdoc-1.0.7}/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.6 → drf_to_mkdoc-1.0.7}/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.6 → drf_to_mkdoc-1.0.7}/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.6 → drf_to_mkdoc-1.0.7}/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.6 → drf_to_mkdoc-1.0.7}/drf_to_mkdoc/conf/settings.py

@@ -1,6 +1,8 @@
 from django.conf import settings
+
 from drf_to_mkdoc.conf.defaults import DEFAULTS
 
+
 class DRFToMkDocSettings:
     required_settings = ["DJANGO_APPS"]
 
@@ -12,15 +14,15 @@ class DRFToMkDocSettings:
     def get(self, key):
         if key not in self.defaults:
             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 +30,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.6 → drf_to_mkdoc-1.0.7}/drf_to_mkdoc/management/commands/build_docs.py

@@ -1,11 +1,12 @@
+import shutil
 import subprocess
 from pathlib import Path
 
-from django.conf import settings
-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.conf import settings
 from django.core.management import call_command
+from django.core.management.base import BaseCommand, CommandError
+from your_app import drf_to_mkdoc_settings  # Replace with your actual import
 
 
 class Command(BaseCommand):
@@ -18,13 +19,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 +35,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 +45,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 +53,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.6 → drf_to_mkdoc-1.0.7}/drf_to_mkdoc/management/commands/generate_docs.py

@@ -4,6 +4,7 @@ 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,
@@ -11,8 +12,6 @@ from drf_to_mkdoc.utils.endpoint_generator import (
     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
-
 
 
 class Command(BaseCommand):

{drf_to_mkdoc-0.1.6 → drf_to_mkdoc-1.0.7}/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"
 

{drf_to_mkdoc-0.1.6 → drf_to_mkdoc-1.0.7}/drf_to_mkdoc/utils/common.py

@@ -1,19 +1,21 @@
-from asyncio.log import logger
 import importlib
-import yaml
 import json
 import re
+from asyncio.log import logger
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
+import yaml
 from django.apps import apps
 from django.core.exceptions import AppRegistryNotReady
 from django.urls import resolve
 from django.utils.module_loading import import_string
 from drf_spectacular.generators import SchemaGenerator
+
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
 
+
 class SchemaValidationError(Exception):
     """Custom exception for schema validation errors."""
 
@@ -37,9 +39,10 @@ def substitute_path_params(path: str, parameters: list[dict[str, Any]]) -> str:
     django_path = re.sub(r"<path:[^>]+>", "dummy/path", django_path)
     django_path = re.sub(r"<[^:>]+>", "dummy", django_path)  # Catch remaining simple params
 
-    return django_path
+    return django_path  # noqa: RET504
+
 
-def load_schema() -> Optional[dict[str, Any]]:
+def load_schema() -> dict[str, Any] | None:
     """Load the OpenAPI schema from doc-schema.yaml"""
     schema_file = Path(drf_to_mkdoc_settings.CONFIG_DIR) / "doc-schema.yaml"
     if not schema_file.exists():
@@ -49,7 +52,7 @@ def load_schema() -> Optional[dict[str, Any]]:
         return yaml.safe_load(f)
 
 
-def load_model_json_data() -> Optional[dict[str, Any]]:
+def load_model_json_data() -> dict[str, Any] | None:
     """Load the JSON mapping data for model information"""
     json_file = Path(drf_to_mkdoc_settings.MODEL_DOCS_FILE)
     if not json_file.exists():
@@ -59,7 +62,7 @@ def load_model_json_data() -> Optional[dict[str, Any]]:
         return json.load(f)
 
 
-def load_doc_config() -> Optional[dict[str, Any]]:
+def load_doc_config() -> dict[str, Any] | None:
     """Load the documentation configuration file"""
     config_file = Path(drf_to_mkdoc_settings.DOC_CONFIG_FILE)
     if not config_file.exists():
@@ -69,7 +72,7 @@ def load_doc_config() -> Optional[dict[str, Any]]:
         return json.load(f)
 
 
-def get_model_docstring(class_name: str) -> Optional[str]:
+def get_model_docstring(class_name: str) -> str | None:
     """Extract docstring from Django model class"""
     try:
         # Check if Django is properly initialized
@@ -167,6 +170,7 @@ def get_custom_schema():
                     raise QueryParamTypeError("Invalid queryparam_type")
     return data
 
+
 def convert_to_django_path(path: str, parameters: list[dict[str, Any]]) -> str:
     """
     Convert a path with {param} to a Django-style path with <type:param>.
@@ -193,26 +197,27 @@ def convert_to_django_path(path: str, parameters: list[dict[str, Any]]) -> str:
     # Default Django path conversion
     def replacement(match):
         param_name = match.group(1)
-        param_info = next((p for p in parameters if p.get('name') == param_name), {})
-        param_type = param_info.get('schema', {}).get('type')
-        param_format = param_info.get('schema', {}).get('format')
-
-        if param_type == 'integer':
-            converter = 'int'
-        elif param_type == 'string' and param_format == 'uuid':
-            converter = 'uuid'
+        param_info = next((p for p in parameters if p.get("name") == param_name), {})
+        param_type = param_info.get("schema", {}).get("type")
+        param_format = param_info.get("schema", {}).get("format")
+
+        if param_type == "integer":
+            converter = "int"
+        elif param_type == "string" and param_format == "uuid":
+            converter = "uuid"
         else:
-            converter = 'str'
+            converter = "str"
 
-        return f'<{converter}:{param_name}>'
+        return f"<{converter}:{param_name}>"
 
-    django_path = re.sub(r'{(\w+)}', replacement, path)
+    django_path = re.sub(r"{(\w+)}", replacement, path)
 
-    if not django_path.endswith('/'):
-        django_path += '/'
+    if not django_path.endswith("/"):
+        django_path += "/"
 
     return django_path
 
+
 @lru_cache
 def get_schema():
     base_schema = SchemaGenerator().get_schema(request=None, public=True)
@@ -291,7 +296,7 @@ def extract_viewset_from_operation_id(operation_id: str):
         else:
             return view_func
 
-    except Exception as e:
+    except Exception:
         logger.error(f"Failed to resolve path {path}")