drf-to-mkdoc 0.2.3__tar.gz → 0.3.0__tar.gz

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.2.3
+Version: 0.3.0
 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>
@@ -55,7 +55,10 @@ Generate beautiful, interactive Markdown API documentation from Django REST Fram
 
 - **Zero-hassle docs**: Beautiful, always-in-sync API docs straight from your codebase
 - **Model deep dive**: Auto-generated model pages with fields, relationships, and choices
+- **ER Diagrams**: Entity-Relationship diagrams showing model relationships
 - **Lightning-fast discovery**: Interactive endpoint index with powerful filters and search
+- **Try-it-out**: Interactive API testing directly in the documentation with request/response examples
+- **AI-powered**: Optional AI-generated documentation with custom field generators(Wait for it...)
 - **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed
 - **MkDocs Material**: Looks great out of the box with the Material theme
 
@@ -76,7 +79,7 @@ INSTALLED_APPS = [
 
 # Required for OpenAPI schema generation
 REST_FRAMEWORK = {
-    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',  # Use our custom AutoSchema
+    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',
 }
 
 SPECTACULAR_SETTINGS = {
@@ -94,16 +97,25 @@ DRF_TO_MKDOC = {
         'inventory',
     ],
     # Optional: Override default paths
-    # 'DOCS_DIR': 'docs',
+    # 'DOCS_DIR': 'docs',  # Base directory for all generated docs
     # 'CONFIG_DIR': 'docs/configs',
+    # 'ER_DIAGRAMS_DIR': 'er_diagrams',  # Directory for ER diagrams (relative to DOCS_DIR)
     # 'MODEL_DOCS_FILE': 'docs/model-docs.json',
     # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',
     # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',
+    # 'FIELD_GENERATORS': {
+    #     'email': 'faker.email',
+    #     'name': 'faker.name',
+    #     'created_at': 'datetime.now',
+    # },
+    # 'ENABLE_AI_DOCS': False,
 }
 ```
 
 2. **Create MkDocs configuration**:  
    Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.
+   
+   **Note**: If you change the `ER_DIAGRAMS_DIR` setting, update the navigation path in `mkdocs.yml` accordingly.
 
 3. **Build documentation**:
 
@@ -111,18 +123,61 @@ DRF_TO_MKDOC = {
 python manage.py build_docs --settings=docs_settings
 ```
 
+### Configuration Options
+
+The `DRF_TO_MKDOC` setting supports several configuration options:
+
+- **`DJANGO_APPS`** (required): List of Django app names to process
+- **`DOCS_DIR`**: Base directory where docs will be generated (default: `docs`)
+- **`CONFIG_DIR`**: Directory for configuration files (default: `docs/configs`)
+- **`ER_DIAGRAMS_DIR`**: Directory for ER diagrams (default: `er_diagrams`, relative to `DOCS_DIR`)
+- **`FIELD_GENERATORS`**: Custom field value generators for better examples
+- **`ENABLE_AI_DOCS`**: Enable AI-powered documentation features (default: `False`)
+- **`PATH_PARAM_SUBSTITUTE_FUNCTION`**: Custom function for path parameter substitution
+- **`PATH_PARAM_SUBSTITUTE_MAPPING`**: Mapping for path parameter substitution
+
 ## Available Commands
 
 - `build_docs`: Build the complete documentation site with MkDocs
 - `build_endpoint_docs`: Build endpoint documentation from OpenAPI schema
 - `build_model_docs`: Build model documentation from model JSON data
 - `extract_model_data`: Extract model data from Django model introspection and save as JSON
+- `generate_doc_json`: Generate JSON context for new API endpoints to be documented
 - `update_doc_schema`: Update the final schema by copying the documented schema
 
 ## What you get
 
 See a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.
 
+## Key Features
+
+### 🚀 Interactive API Testing (Try-Out)
+- **Live API testing**: Test endpoints directly from the documentation
+- **Request builder**: Interactive forms for parameters, headers, and request body
+- **Response viewer**: Real-time response display with syntax highlighting
+- **Floating action button**: Easy access to testing interface
+- **Multiple examples**: Support for both empty and populated response examples
+
+### 📊 Entity-Relationship Diagrams
+- **Visual model relationships**: Interactive ER diagrams showing all model connections
+- **App-specific views**: Detailed diagrams for each Django app with field information
+- **Mermaid-powered**: Clean, professional diagrams with zoom and navigation controls
+- **Auto-generated**: Automatically created from your Django model relationships
+
+### 🤖 AI-Powered Documentation
+- **Custom field generators**: Define custom value generators for specific fields
+- **AI documentation**: Optional AI-generated documentation with context analysis
+- **Smart examples**: Enhanced example generation for better API understanding
+
+### 📊 Advanced Filtering & Search
+- **Multi-criteria filtering**: Filter by app, HTTP method, path, and search terms
+- **Real-time search**: Instant search across all endpoints
+- **Smart suggestions**: Auto-complete for query parameters and field names
+
+### 🎨 Beautiful UI
+- **Material Design**: Modern, responsive interface with dark/light themes
+- **Interactive elements**: Hover effects, animations, and smooth transitions
+- **Mobile-friendly**: Fully responsive design for all devices
 
 ## How it works
 
@@ -167,13 +222,33 @@ drf-to-mkdoc/
 │   │       ├── build_endpoint_docs.py  # Build endpoint documentation
 │   │       ├── build_model_docs.py     # Build model documentation
 │   │       ├── extract_model_data.py   # Extract model data from Django
+│   │       ├── generate_doc_json.py    # Generate JSON context for AI docs
 │   │       └── update_doc_schema.py    # Schema updates
+│   ├── static/
+│   │   └── drf-to-mkdoc/
+│   │       ├── javascripts/
+│   │       │   ├── try-out/            # Interactive API testing
+│   │       │   └── endpoints-filter.js # Endpoint filtering
+│   │       └── stylesheets/            # CSS for styling
+│   ├── templates/
+│   │   ├── endpoints/                  # Endpoint documentation templates
+│   │   ├── model_detail/               # Model documentation templates
+│   │   └── try-out/                    # Interactive testing templates
 │   └── utils/
-│       ├── common.py        # Shared utilities
-│       ├── endpoint_generator.py  # Endpoint documentation
-│       ├── model_generator.py     # Model documentation
-│       └── extractors/      # Query parameter extraction
-├── pyproject.toml           # Project configuration
+│       ├── ai_tools/                   # AI-powered documentation features
+│       ├── commons/                    # Shared utilities
+│       ├── extractors/                 # Query parameter extraction
+│       ├── endpoint_detail_generator.py
+│       ├── endpoint_list_generator.py
+│       ├── model_detail_generator.py
+│       ├── model_list_generator.py
+│       └── schema.py
+├── docs/                      # Generated documentation
+│   ├── endpoints/             # API endpoint documentation
+│   ├── models/                # Model documentation
+│   ├── er_diagrams/           # Entity-Relationship diagrams
+│   └── configs/               # Configuration files
+├── pyproject.toml            # Project configuration
 └── README.md
 ```
 
@@ -191,6 +266,7 @@ To avoid committing generated files to your repository, add the following to you
 # Documentation
 /docs/endpoints/
 /docs/models/
+/docs/er_diagrams/
 /docs/configs/doc-schema.yaml
 
 # Build artifacts
@@ -227,10 +303,13 @@ your-project/
 ├── docs_settings.py     # Documentation-specific settings
 ├── mkdocs.yml          # MkDocs configuration
 ├── docs/               # Generated documentation (gitignored)
+│   ├── endpoints/      # API endpoint docs
+│   ├── models/         # Model documentation
+│   ├── er_diagrams/    # ER diagrams
+│   └── configs/        # Configuration files
 └── site/               # Built site (gitignored)
 ```
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines. 
-This will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/README.md

@@ -6,7 +6,10 @@ Generate beautiful, interactive Markdown API documentation from Django REST Fram
 
 - **Zero-hassle docs**: Beautiful, always-in-sync API docs straight from your codebase
 - **Model deep dive**: Auto-generated model pages with fields, relationships, and choices
+- **ER Diagrams**: Entity-Relationship diagrams showing model relationships
 - **Lightning-fast discovery**: Interactive endpoint index with powerful filters and search
+- **Try-it-out**: Interactive API testing directly in the documentation with request/response examples
+- **AI-powered**: Optional AI-generated documentation with custom field generators(Wait for it...)
 - **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed
 - **MkDocs Material**: Looks great out of the box with the Material theme
 
@@ -27,7 +30,7 @@ INSTALLED_APPS = [
 
 # Required for OpenAPI schema generation
 REST_FRAMEWORK = {
-    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',  # Use our custom AutoSchema
+    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',
 }
 
 SPECTACULAR_SETTINGS = {
@@ -45,16 +48,25 @@ DRF_TO_MKDOC = {
         'inventory',
     ],
     # Optional: Override default paths
-    # 'DOCS_DIR': 'docs',
+    # 'DOCS_DIR': 'docs',  # Base directory for all generated docs
     # 'CONFIG_DIR': 'docs/configs',
+    # 'ER_DIAGRAMS_DIR': 'er_diagrams',  # Directory for ER diagrams (relative to DOCS_DIR)
     # 'MODEL_DOCS_FILE': 'docs/model-docs.json',
     # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',
     # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',
+    # 'FIELD_GENERATORS': {
+    #     'email': 'faker.email',
+    #     'name': 'faker.name',
+    #     'created_at': 'datetime.now',
+    # },
+    # 'ENABLE_AI_DOCS': False,
 }
 ```
 
 2. **Create MkDocs configuration**:  
    Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.
+   
+   **Note**: If you change the `ER_DIAGRAMS_DIR` setting, update the navigation path in `mkdocs.yml` accordingly.
 
 3. **Build documentation**:
 
@@ -62,18 +74,61 @@ DRF_TO_MKDOC = {
 python manage.py build_docs --settings=docs_settings
 ```
 
+### Configuration Options
+
+The `DRF_TO_MKDOC` setting supports several configuration options:
+
+- **`DJANGO_APPS`** (required): List of Django app names to process
+- **`DOCS_DIR`**: Base directory where docs will be generated (default: `docs`)
+- **`CONFIG_DIR`**: Directory for configuration files (default: `docs/configs`)
+- **`ER_DIAGRAMS_DIR`**: Directory for ER diagrams (default: `er_diagrams`, relative to `DOCS_DIR`)
+- **`FIELD_GENERATORS`**: Custom field value generators for better examples
+- **`ENABLE_AI_DOCS`**: Enable AI-powered documentation features (default: `False`)
+- **`PATH_PARAM_SUBSTITUTE_FUNCTION`**: Custom function for path parameter substitution
+- **`PATH_PARAM_SUBSTITUTE_MAPPING`**: Mapping for path parameter substitution
+
 ## Available Commands
 
 - `build_docs`: Build the complete documentation site with MkDocs
 - `build_endpoint_docs`: Build endpoint documentation from OpenAPI schema
 - `build_model_docs`: Build model documentation from model JSON data
 - `extract_model_data`: Extract model data from Django model introspection and save as JSON
+- `generate_doc_json`: Generate JSON context for new API endpoints to be documented
 - `update_doc_schema`: Update the final schema by copying the documented schema
 
 ## What you get
 
 See a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.
 
+## Key Features
+
+### 🚀 Interactive API Testing (Try-Out)
+- **Live API testing**: Test endpoints directly from the documentation
+- **Request builder**: Interactive forms for parameters, headers, and request body
+- **Response viewer**: Real-time response display with syntax highlighting
+- **Floating action button**: Easy access to testing interface
+- **Multiple examples**: Support for both empty and populated response examples
+
+### 📊 Entity-Relationship Diagrams
+- **Visual model relationships**: Interactive ER diagrams showing all model connections
+- **App-specific views**: Detailed diagrams for each Django app with field information
+- **Mermaid-powered**: Clean, professional diagrams with zoom and navigation controls
+- **Auto-generated**: Automatically created from your Django model relationships
+
+### 🤖 AI-Powered Documentation
+- **Custom field generators**: Define custom value generators for specific fields
+- **AI documentation**: Optional AI-generated documentation with context analysis
+- **Smart examples**: Enhanced example generation for better API understanding
+
+### 📊 Advanced Filtering & Search
+- **Multi-criteria filtering**: Filter by app, HTTP method, path, and search terms
+- **Real-time search**: Instant search across all endpoints
+- **Smart suggestions**: Auto-complete for query parameters and field names
+
+### 🎨 Beautiful UI
+- **Material Design**: Modern, responsive interface with dark/light themes
+- **Interactive elements**: Hover effects, animations, and smooth transitions
+- **Mobile-friendly**: Fully responsive design for all devices
 
 ## How it works
 
@@ -118,13 +173,33 @@ drf-to-mkdoc/
 │   │       ├── build_endpoint_docs.py  # Build endpoint documentation
 │   │       ├── build_model_docs.py     # Build model documentation
 │   │       ├── extract_model_data.py   # Extract model data from Django
+│   │       ├── generate_doc_json.py    # Generate JSON context for AI docs
 │   │       └── update_doc_schema.py    # Schema updates
+│   ├── static/
+│   │   └── drf-to-mkdoc/
+│   │       ├── javascripts/
+│   │       │   ├── try-out/            # Interactive API testing
+│   │       │   └── endpoints-filter.js # Endpoint filtering
+│   │       └── stylesheets/            # CSS for styling
+│   ├── templates/
+│   │   ├── endpoints/                  # Endpoint documentation templates
+│   │   ├── model_detail/               # Model documentation templates
+│   │   └── try-out/                    # Interactive testing templates
 │   └── utils/
-│       ├── common.py        # Shared utilities
-│       ├── endpoint_generator.py  # Endpoint documentation
-│       ├── model_generator.py     # Model documentation
-│       └── extractors/      # Query parameter extraction
-├── pyproject.toml           # Project configuration
+│       ├── ai_tools/                   # AI-powered documentation features
+│       ├── commons/                    # Shared utilities
+│       ├── extractors/                 # Query parameter extraction
+│       ├── endpoint_detail_generator.py
+│       ├── endpoint_list_generator.py
+│       ├── model_detail_generator.py
+│       ├── model_list_generator.py
+│       └── schema.py
+├── docs/                      # Generated documentation
+│   ├── endpoints/             # API endpoint documentation
+│   ├── models/                # Model documentation
+│   ├── er_diagrams/           # Entity-Relationship diagrams
+│   └── configs/               # Configuration files
+├── pyproject.toml            # Project configuration
 └── README.md
 ```
 
@@ -142,6 +217,7 @@ To avoid committing generated files to your repository, add the following to you
 # Documentation
 /docs/endpoints/
 /docs/models/
+/docs/er_diagrams/
 /docs/configs/doc-schema.yaml
 
 # Build artifacts
@@ -178,10 +254,13 @@ your-project/
 ├── docs_settings.py     # Documentation-specific settings
 ├── mkdocs.yml          # MkDocs configuration
 ├── docs/               # Generated documentation (gitignored)
+│   ├── endpoints/      # API endpoint docs
+│   ├── models/         # Model documentation
+│   ├── er_diagrams/    # ER diagrams
+│   └── configs/        # Configuration files
 └── site/               # Built site (gitignored)
 ```
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines. 
-This will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/docs/customizing_endpoints.md

@@ -1,7 +1,7 @@
 
 # Customizing API Endpoint Documentation
 
-`drf-to-mkdoc` automatically generates API documentation from your Django REST Framework (DRF) project using the OpenAPI schema from **DRF Spectacular**. You can refine and extend that documentation using a **custom JSON file**.
+`drf-to-mkdoc` automatically generates API documentation from your Django REST Framework (DRF) project using the OpenAPI schema from **DRF Spectacular**. You can refine and extend that documentation using a **custom JSON file** and various configuration options.
 
 ---
 
@@ -170,3 +170,33 @@ Supported `queryparam_type` values:
 * Keep `custom_schema.json` in version control so your team benefits.
 * Start small: add descriptions first, then parameters, then responses.
 * Use `append_fields` if you want to **add extra info** without overwriting auto-generated items.
+
+---
+
+## 7. Advanced Configuration Options
+
+### Field Generators
+You can define custom field value generators for better example generation:
+
+```python
+DRF_TO_MKDOC = {
+    'DJANGO_APPS': ['your_apps'],
+    'FIELD_GENERATORS': {
+        'created_at': datetime.now.strftime(settings.CUSTOM_DATETIME_FORMAT),
+        'phone_number': generate_phone_number_function,
+    },
+}
+```
+
+### Path Parameter Substitution
+Customize how path parameters are handled:
+
+```python
+DRF_TO_MKDOC = {
+    'PATH_PARAM_SUBSTITUTE_FUNCTION': 'your_app.utils.custom_substitute',
+    'PATH_PARAM_SUBSTITUTE_MAPPING': {
+        'pk': 'id',
+        'uuid': 'identifier',
+    },
+}
+```

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/docs/mkdocs.yml

@@ -37,6 +37,7 @@ plugins:
 nav:
   - Home: index.md
   - Models: models/
+  - ER Diagrams: er_diagrams/  # ER_DIAGRAMS_DIR setting
   - API Endpoints: endpoints/
 
 markdown_extensions:

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/drf_to_mkdoc/conf/defaults.py

@@ -2,6 +2,7 @@ DEFAULTS = {
     # Path configurations with defaults
     "DOCS_DIR": "docs",  # Directory where docs will be generated
     "CONFIG_DIR": "docs/configs",  # Directory for configuration files
+    "ER_DIAGRAMS_DIR": "er_diagrams",  # Directory for ER diagrams (relative to DOCS_DIR)
     "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

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/drf_to_mkdoc/conf/settings.py

@@ -22,6 +22,7 @@ class DRFToMkDocSettings:
 
     path_settings = {
         "CONFIG_DIR",
+        "ER_DIAGRAMS_DIR",
         "MODEL_DOCS_FILE",
         "DOC_CONFIG_FILE",
         "CUSTOM_SCHEMA_FILE",

{drf_to_mkdoc-0.2.3 → drf_to_mkdoc-0.3.0}/drf_to_mkdoc/management/commands/build_model_docs.py

@@ -4,6 +4,7 @@ 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.er_diagram_generator import generate_er_diagrams
 from drf_to_mkdoc.utils.model_detail_generator import generate_model_docs
 from drf_to_mkdoc.utils.model_list_generator import create_models_index
 
@@ -42,9 +43,17 @@ class Command(BaseCommand):
         self.stdout.write("📋 Generating model documentation...")
 
         try:
+            # Generate model detail pages
             generate_model_docs(models_data)
+            self.stdout.write(self.style.SUCCESS("✅ Model detail pages generated"))
+
+            # Generate ER diagrams
+            generate_er_diagrams(models_data, docs_dir)
+            self.stdout.write(self.style.SUCCESS("✅ ER diagrams generated"))
+
+            # Create models index page
             create_models_index(models_data, docs_dir)
-            self.stdout.write(self.style.SUCCESS("✅ Model documentation generated"))
+            self.stdout.write(self.style.SUCCESS("✅ Models index page generated"))
         except Exception as e:
             self.stdout.write(self.style.WARNING(f"⚠️  Failed to generate model docs: {e}"))
             raise

drf_to_mkdoc-0.3.0/drf_to_mkdoc/static/drf-to-mkdoc/javascripts/field-sections-loader.js

@@ -0,0 +1,29 @@
+// Loader script for field sections functionality
+document.addEventListener('DOMContentLoaded', function() {
+    // Load CSS
+    function loadCSS(url) {
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = url;
+        document.head.appendChild(link);
+    }
+    
+    // Load JavaScript
+    function loadScript(url, callback) {
+        const script = document.createElement('script');
+        script.src = url;
+        script.onload = callback || function() {};
+        document.body.appendChild(script);
+    }
+    
+    // Base URL for static files
+    const baseUrl = document.querySelector('meta[name="static-url"]')?.getAttribute('content') || '';
+    
+    // Load CSS file
+    loadCSS(baseUrl + '/static/drf-to-mkdoc/stylesheets/field-sections.css');
+    
+    // Load field extractor script
+    loadScript(baseUrl + '/static/drf-to-mkdoc/javascripts/try-out/field-extractor.js');
+    
+    console.log('Field sections functionality loaded');
+});

drf_to_mkdoc-0.3.0/drf_to_mkdoc/static/drf-to-mkdoc/javascripts/query-parameters-loader.js

@@ -0,0 +1,16 @@
+// Query parameters loader script
+document.addEventListener('DOMContentLoaded', function() {
+    // Load JavaScript
+    function loadScript(url, callback) {
+        const script = document.createElement('script');
+        script.src = url;
+        script.onload = callback || function() {};
+        document.body.appendChild(script);
+    }
+    
+    // Base URL for static files
+    const baseUrl = document.querySelector('meta[name="static-url"]')?.getAttribute('content') || '';
+    
+    // Load query parameters extractor script
+    loadScript(baseUrl + '/static/drf-to-mkdoc/javascripts/try-out/query-parameters-extractor.js');
+});