drf-to-mkdoc 0.1.0__tar.gz

drf_to_mkdoc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ShayestehHs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

drf_to_mkdoc-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+include MANIFEST.in
+include pyproject.toml
+
+recursive-include drf_to_mkdoc/conf *.py
+recursive-include drf_to_mkdoc/utils *.py
+recursive-include drf_to_mkdoc/management *.py
+
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude .git*
+global-exclude .idea
+global-exclude .venv
+global-exclude .env
+global-exclude *.log

drf_to_mkdoc-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: drf-to-mkdoc
+Version: 0.1.0
+Summary: Generate Markdown API docs from Django/DRF OpenAPI schema for MkDocs
+Author-email: Your Name <your@email.com>
+Maintainer-email: Your Name <your@email.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/drf-to-mkdoc
+Project-URL: Repository, https://github.com/yourusername/drf-to-mkdoc
+Project-URL: Documentation, https://github.com/yourusername/drf-to-mkdoc#readme
+Project-URL: Bug Tracker, https://github.com/yourusername/drf-to-mkdoc/issues
+Keywords: django,django-rest-framework,documentation,mkdocs,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<6.0,>=3.2
+Requires-Dist: djangorestframework<4.0,>=3.12
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: drf-spectacular>=0.26.0
+Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: mkdocs-material>=9.0.0
+Requires-Dist: coreapi>=2.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# DRF to MkDocs
+
+Generate beautiful, interactive Markdown API documentation from Django REST Framework OpenAPI schema for MkDocs.
+
+## Why you'll love it
+
+- **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
+- **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed
+- **MkDocs Material**: Looks great out of the box with the Material theme
+
+## Installation
+
+See the full installation guide in `docs/installation.md`.
+
+## Quick Start
+
+1. **Configure your Django project**:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ... your other apps
+    'drf_to_mkdoc',
+]
+
+# Required for OpenAPI schema generation
+REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+}
+
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Your API',
+    'DESCRIPTION': 'Your API description',
+    'VERSION': '1.0.0',
+}
+
+DRF_TO_MKDOC = {
+    'DJANGO_APPS': [
+        'users',
+        'products',
+        'orders',
+        'inventory',
+    ],
+    # Optional: Override default paths
+    # 'DOCS_DIR': 'docs',
+    # 'CONFIG_DIR': 'docs/configs',
+    # 'MODEL_DOCS_FILE': 'docs/model-docs.json',
+    # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',
+    # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',
+}
+```
+
+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
+```
+
+3. **Build documentation**:
+
+```bash
+python manage.py build_docs --settings=docs_settings
+```
+
+## What you get
+
+See a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.
+
+## How it works
+
+Under the hood, drf-to-mkdoc introspects your models and reads your DRF OpenAPI schema to generate clean, organized Markdown. Then MkDocs turns it into a polished static site. Always current, no manual updates.
+
+## Explore more
+
+- Customizing endpoint docs: `docs/customizing_endpoints.md`
+- Serving docs through Django (with permissions): `docs/serving_mkdocs_with_django.md`
+
+## Dependencies
+
+- Django >= 3.2, < 6.0
+- Django REST Framework >= 3.12, < 4.0
+- drf-spectacular >= 0.26.0
+- PyYAML >= 6.0
+- MkDocs >= 1.4.0
+- MkDocs Material >= 9.0.0
+- coreapi >= 2.3.0
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/yourusername/drf-to-mkdoc.git
+cd drf-to-mkdoc
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+```
+drf-to-mkdoc/
+├── drf_to_mkdoc/
+│   ├── conf/
+│   │   ├── defaults.py      # Default configuration values
+│   │   └── settings.py      # Settings management
+│   ├── management/
+│   │   └── commands/
+│   │       ├── build_docs.py           # Build MkDocs site
+│   │       ├── generate_docs.py        # Main documentation generator
+│   │       ├── generate_model_docs.py  # Model documentation
+│   │       └── update_doc_schema.py    # Schema updates
+│   └── utils/
+│       ├── common.py        # Shared utilities
+│       ├── endpoint_generator.py  # Endpoint documentation
+│       ├── model_generator.py     # Model documentation
+│       └── extractors/      # Query parameter extraction
+├── pyproject.toml           # Project configuration
+└── README.md
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Recommendations
+
+### .gitignore Configuration
+
+To avoid committing generated files to your repository, add the following to your `.gitignore` file:
+
+```gitignore
+# Documentation
+/docs/endpoints/
+/docs/models/
+/docs/configs/doc-schema.yaml
+
+# Build artifacts
+/site/
+```
+
+This will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.
+
+### docs_settings.py Best Practices
+
+Create a separate `docs_settings.py` file that inherits from your main settings:
+
+```python
+# docs_settings.py
+from .settings import *
+
+DRF_TO_MKDOC = {
+    'DJANGO_APPS': ['your_app1', 'your_app2'],
+}
+# Other doc settings...
+```
+
+Then use the `--settings` argument when running the build command:
+
+```bash
+python manage.py build_docs --settings=docs_settings
+```
+
+### Project Organization
+
+```
+your-project/
+├── settings.py          # Main Django settings
+├── docs_settings.py     # Documentation-specific settings
+├── mkdocs.yml          # MkDocs configuration
+├── docs/               # Generated documentation (gitignored)
+└── 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. 

drf_to_mkdoc-0.1.0/README.md

@@ -0,0 +1,198 @@
+# DRF to MkDocs
+
+Generate beautiful, interactive Markdown API documentation from Django REST Framework OpenAPI schema for MkDocs.
+
+## Why you'll love it
+
+- **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
+- **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed
+- **MkDocs Material**: Looks great out of the box with the Material theme
+
+## Installation
+
+See the full installation guide in `docs/installation.md`.
+
+## Quick Start
+
+1. **Configure your Django project**:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ... your other apps
+    'drf_to_mkdoc',
+]
+
+# Required for OpenAPI schema generation
+REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+}
+
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Your API',
+    'DESCRIPTION': 'Your API description',
+    'VERSION': '1.0.0',
+}
+
+DRF_TO_MKDOC = {
+    'DJANGO_APPS': [
+        'users',
+        'products',
+        'orders',
+        'inventory',
+    ],
+    # Optional: Override default paths
+    # 'DOCS_DIR': 'docs',
+    # 'CONFIG_DIR': 'docs/configs',
+    # 'MODEL_DOCS_FILE': 'docs/model-docs.json',
+    # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',
+    # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',
+}
+```
+
+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
+```
+
+3. **Build documentation**:
+
+```bash
+python manage.py build_docs --settings=docs_settings
+```
+
+## What you get
+
+See a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.
+
+## How it works
+
+Under the hood, drf-to-mkdoc introspects your models and reads your DRF OpenAPI schema to generate clean, organized Markdown. Then MkDocs turns it into a polished static site. Always current, no manual updates.
+
+## Explore more
+
+- Customizing endpoint docs: `docs/customizing_endpoints.md`
+- Serving docs through Django (with permissions): `docs/serving_mkdocs_with_django.md`
+
+## Dependencies
+
+- Django >= 3.2, < 6.0
+- Django REST Framework >= 3.12, < 4.0
+- drf-spectacular >= 0.26.0
+- PyYAML >= 6.0
+- MkDocs >= 1.4.0
+- MkDocs Material >= 9.0.0
+- coreapi >= 2.3.0
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/yourusername/drf-to-mkdoc.git
+cd drf-to-mkdoc
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+```
+drf-to-mkdoc/
+├── drf_to_mkdoc/
+│   ├── conf/
+│   │   ├── defaults.py      # Default configuration values
+│   │   └── settings.py      # Settings management
+│   ├── management/
+│   │   └── commands/
+│   │       ├── build_docs.py           # Build MkDocs site
+│   │       ├── generate_docs.py        # Main documentation generator
+│   │       ├── generate_model_docs.py  # Model documentation
+│   │       └── update_doc_schema.py    # Schema updates
+│   └── utils/
+│       ├── common.py        # Shared utilities
+│       ├── endpoint_generator.py  # Endpoint documentation
+│       ├── model_generator.py     # Model documentation
+│       └── extractors/      # Query parameter extraction
+├── pyproject.toml           # Project configuration
+└── README.md
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Recommendations
+
+### .gitignore Configuration
+
+To avoid committing generated files to your repository, add the following to your `.gitignore` file:
+
+```gitignore
+# Documentation
+/docs/endpoints/
+/docs/models/
+/docs/configs/doc-schema.yaml
+
+# Build artifacts
+/site/
+```
+
+This will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.
+
+### docs_settings.py Best Practices
+
+Create a separate `docs_settings.py` file that inherits from your main settings:
+
+```python
+# docs_settings.py
+from .settings import *
+
+DRF_TO_MKDOC = {
+    'DJANGO_APPS': ['your_app1', 'your_app2'],
+}
+# Other doc settings...
+```
+
+Then use the `--settings` argument when running the build command:
+
+```bash
+python manage.py build_docs --settings=docs_settings
+```
+
+### Project Organization
+
+```
+your-project/
+├── settings.py          # Main Django settings
+├── docs_settings.py     # Documentation-specific settings
+├── mkdocs.yml          # MkDocs configuration
+├── docs/               # Generated documentation (gitignored)
+└── 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. 

drf_to_mkdoc-0.1.0/drf_to_mkdoc/__init__.py

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

drf_to_mkdoc-0.1.0/drf_to_mkdoc/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+
+
+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 

drf_to_mkdoc-0.1.0/drf_to_mkdoc/conf/defaults.py

@@ -0,0 +1,11 @@
+DEFAULTS = {
+    # Path configurations with defaults
+    "DOCS_DIR": "docs",  # Directory where docs will be generated
+    "CONFIG_DIR": "docs/configs",  # Directory for configuration files
+    "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.0/drf_to_mkdoc/conf/settings.py

@@ -0,0 +1,44 @@
+from django.conf import settings
+from drf_to_mkdoc.conf.defaults import DEFAULTS
+
+class DRFToMkDocSettings:
+    required_settings = ["DJANGO_APPS"]
+
+    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:
+            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):
+        return self.get(key)
+
+    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.0/drf_to_mkdoc/management/commands/build_docs.py

@@ -0,0 +1,76 @@
+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.core.management import call_command
+
+
+class Command(BaseCommand):
+    help = "Build MkDocs documentation"
+
+    def handle(self, *args, **options):
+        drf_to_mkdoc_settings.validate_required_settings()
+        self.stdout.write(self.style.SUCCESS("✅ DRF_TO_MKDOC settings validated."))
+
+        try:
+            apps.check_apps_ready()
+        except Exception as e:
+            raise CommandError(f"Django apps not properly configured: {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' "
+                "in your project root directory."
+            )
+
+        try:
+            # Generate the model documentation JSON first
+            self.stdout.write("Generating model documentation...")
+
+            try:
+                call_command(
+                    "generate_model_docs", "--pretty"
+                )
+                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}"))
+
+            # Generate the documentation content
+            self.stdout.write("Generating documentation content...")
+            try:
+                call_command("generate_docs")
+                self.stdout.write(self.style.SUCCESS("Documentation content generated."))
+            except Exception as e:
+                self.stdout.write(self.style.ERROR(f"Failed to generate docs: {e}"))
+                raise
+
+            # 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.stdout.write(self.style.SUCCESS("Documentation built successfully!"))
+            self.stdout.write(f"Site built in: {site_dir}")
+
+        except FileNotFoundError as e:
+            raise CommandError(
+                "MkDocs not found. Please install it with: pip install mkdocs mkdocs-material"
+            ) from e
+        except Exception as e:
+            raise CommandError(f"Error building documentation: {e!s}") from e