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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.2.3
+Version: 0.2.4
 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>
@@ -56,6 +56,8 @@ 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
 - **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 +78,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 = {
@@ -99,6 +101,12 @@ DRF_TO_MKDOC = {
     # '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,
 }
 ```
 
@@ -111,18 +119,54 @@ 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`**: Directory where docs will be generated (default: `docs`)
+- **`CONFIG_DIR`**: Directory for configuration files (default: `docs/configs`)
+- **`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
+
+### 🤖 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 +211,29 @@ 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
+├── pyproject.toml            # Project configuration
 └── README.md
 ```
 
@@ -232,5 +292,4 @@ your-project/
 
 ## 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.2.4}/README.md

@@ -7,6 +7,8 @@ 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
 - **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 +29,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 = {
@@ -50,6 +52,12 @@ DRF_TO_MKDOC = {
     # '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,
 }
 ```
 
@@ -62,18 +70,54 @@ 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`**: Directory where docs will be generated (default: `docs`)
+- **`CONFIG_DIR`**: Directory for configuration files (default: `docs/configs`)
+- **`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
+
+### 🤖 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 +162,29 @@ 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
+├── pyproject.toml            # Project configuration
 └── README.md
 ```
 
@@ -183,5 +243,4 @@ your-project/
 
 ## 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.2.4}/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.4/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.2.4/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');
+});

drf_to_mkdoc-0.2.4/drf_to_mkdoc/static/drf-to-mkdoc/javascripts/try-out/field-extractor.js

@@ -0,0 +1,200 @@
+// Field extractor for documentation content
+document.addEventListener('DOMContentLoaded', function() {
+    // Extract filter fields and pagination fields from documentation
+    const FieldExtractor = {
+        init: function() {
+            // Extract fields from documentation
+            const fields = this.extractFieldsFromDocumentation();
+            
+            // Make fields available for suggestions
+            if (fields && (fields.filter_fields.length > 0 || fields.pagination_fields.length > 0)) {
+                window.queryParametersData = window.queryParametersData || {};
+                
+                // Add filter fields
+                if (fields.filter_fields.length > 0) {
+                    window.queryParametersData.filter_fields = fields.filter_fields;
+                }
+                
+                // Add pagination fields
+                if (fields.pagination_fields.length > 0) {
+                    window.queryParametersData.pagination_fields = fields.pagination_fields;
+                }
+                
+                // Initialize suggestions if TryOutSuggestions is available
+                if (window.TryOutSuggestions) {
+                    window.TryOutSuggestions.init();
+                }
+            }
+        },
+        
+        extractFieldsFromDocumentation: function() {
+            const result = {
+                filter_fields: [],
+                pagination_fields: []
+            };
+            
+            // Look for filter fields section
+            const filterFieldsHeading = document.querySelector('h3#filter-fields');
+            if (filterFieldsHeading) {
+                const filterFieldsList = filterFieldsHeading.nextElementSibling;
+                if (filterFieldsList && filterFieldsList.tagName === 'UL') {
+                    const filterFields = Array.from(filterFieldsList.querySelectorAll('li code'))
+                        .map(code => code.textContent.trim());
+                    
+                    if (filterFields.length > 0) {
+                        result.filter_fields = filterFields;
+                    }
+                }
+            }
+            
+            // Look for pagination fields section
+            const paginationFieldsHeading = document.querySelector('h3#pagination-fields');
+            if (paginationFieldsHeading) {
+                const paginationFieldsList = paginationFieldsHeading.nextElementSibling;
+                if (paginationFieldsList && paginationFieldsList.tagName === 'UL') {
+                    const paginationFields = Array.from(paginationFieldsList.querySelectorAll('li code'))
+                        .map(code => code.textContent.trim());
+                    
+                    if (paginationFields.length > 0) {
+                        result.pagination_fields = paginationFields;
+                    }
+                }
+            }
+            
+            return result;
+        },
+        
+        formatDocumentation: function() {
+            // Format filter fields section
+            this.formatSection('filter-fields', 'Filter Fields');
+            
+            // Format pagination fields section
+            this.formatSection('pagination-fields', 'Pagination Fields');
+        },
+        
+        formatSection: function(sectionId, title) {
+            const heading = document.querySelector(`h3#${sectionId}`);
+            if (!heading) return;
+            
+            const list = heading.nextElementSibling;
+            if (!list || list.tagName !== 'UL') return;
+            
+            // Create a new container div
+            const container = document.createElement('div');
+            container.className = 'api-parameters-section';
+            container.id = `${sectionId}-container`;
+            
+            // Create a new heading
+            const newHeading = document.createElement('h3');
+            newHeading.id = sectionId;
+            newHeading.innerHTML = heading.innerHTML;
+            
+            // Create a new list container
+            const listContainer = document.createElement('div');
+            listContainer.className = 'parameters-list';
+            
+            // Create a description paragraph
+            const description = document.createElement('p');
+            description.className = 'parameters-description';
+            
+            if (sectionId === 'filter-fields') {
+                description.textContent = 'These fields can be used to filter the API results. Add them as query parameters to your request.';
+            } else if (sectionId === 'pagination-fields') {
+                description.textContent = 'These fields control pagination of the API results.';
+            }
+            
+            // Process the list items to enhance them
+            const enhancedList = this.enhanceParametersList(list);
+            
+            // Move the list into the container
+            listContainer.appendChild(enhancedList);
+            
+            // Add elements to the container
+            container.appendChild(newHeading);
+            container.appendChild(description);
+            container.appendChild(listContainer);
+            
+            // Replace the old elements with the new container
+            heading.parentNode.insertBefore(container, heading);
+            list.parentNode.removeChild(list);
+            heading.parentNode.removeChild(heading);
+            
+            // Add try-it buttons
+            this.addTryItButtons(container, sectionId);
+        },
+        
+        enhanceParametersList: function(list) {
+            // Clone the list
+            const enhancedList = list.cloneNode(true);
+            
+            // Process each list item
+            Array.from(enhancedList.querySelectorAll('li')).forEach(li => {
+                const code = li.querySelector('code');
+                if (code) {
+                    // Create a button to try this parameter
+                    const tryButton = document.createElement('button');
+                    tryButton.className = 'try-param-btn';
+                    tryButton.textContent = 'Try it';
+                    tryButton.dataset.param = code.textContent.trim();
+                    tryButton.addEventListener('click', (e) => {
+                        e.preventDefault();
+                        this.addParameterToTryOut(e.target.dataset.param);
+                    });
+                    
+                    li.appendChild(tryButton);
+                }
+            });
+            
+            return enhancedList;
+        },
+        
+        addTryItButtons: function(container, sectionId) {
+            // Create a button to try all parameters in this section
+            const tryAllButton = document.createElement('button');
+            tryAllButton.className = 'try-all-params-btn';
+            tryAllButton.textContent = 'Try All Parameters';
+            
+            tryAllButton.addEventListener('click', (e) => {
+                e.preventDefault();
+                
+                // Get all parameters in this section
+                const params = Array.from(container.querySelectorAll('code'))
+                    .map(code => code.textContent.trim());
+                
+                // Add all parameters to try-out form
+                params.forEach(param => this.addParameterToTryOut(param));
+            });
+            
+            // Add the button to the container
+            container.appendChild(tryAllButton);
+        },
+        
+        addParameterToTryOut: function(paramName) {
+            // Find the try-out modal or form
+            const tryOutModal = document.getElementById('tryOutModal');
+            if (!tryOutModal) return;
+            
+            // Show the modal if it's not already visible
+            if (tryOutModal.style.display !== 'flex') {
+                if (window.ModalManager && window.ModalManager.openTryOut) {
+                    window.ModalManager.openTryOut();
+                } else {
+                    tryOutModal.style.display = 'flex';
+                }
+            }
+            
+            // Add the parameter to the query parameters
+            if (window.TryOutSidebar && window.TryOutSidebar.addQueryParam) {
+                window.TryOutSidebar.addQueryParam(paramName);
+            } else if (window.FormManager && window.FormManager.addQueryParam) {
+                window.FormManager.addQueryParam(paramName);
+            }
+        }
+    };
+    
+    // Initialize field extractor
+    FieldExtractor.init();
+    
+    // Format documentation sections
+    FieldExtractor.formatDocumentation();
+});