# 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_to_mkdoc.utils.schema.AutoSchema', # Use our custom 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**:
Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.
3. **Build documentation**:
```bash
python manage.py build_docs --settings=docs_settings
```
## 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
- `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`.
## 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/Shayestehhs/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
│ │ ├── build_endpoint_docs.py # Build endpoint documentation
│ │ ├── build_model_docs.py # Build model documentation
│ │ ├── extract_model_data.py # Extract model data from Django
│ │ └── 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "drf-to-mkdoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Hossein Shayesteh <shayestehhs1@gmail.com>",
"keywords": "django, django-rest-framework, documentation, mkdocs, api",
"author": null,
"author_email": "Hossein Shayesteh <shayestehhs1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/92/11/9ccd3af0179829fdf52992151a0906371b239bc4937470232ded9134cd1c/drf_to_mkdoc-0.2.1.tar.gz",
"platform": null,
"description": "# DRF to MkDocs\n\nGenerate beautiful, interactive Markdown API documentation from Django REST Framework OpenAPI schema for MkDocs.\n\n## Why you'll love it\n\n- **Zero-hassle docs**: Beautiful, always-in-sync API docs straight from your codebase\n- **Model deep dive**: Auto-generated model pages with fields, relationships, and choices\n- **Lightning-fast discovery**: Interactive endpoint index with powerful filters and search\n- **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed\n- **MkDocs Material**: Looks great out of the box with the Material theme\n\n## Installation\n\nSee the full installation guide in `docs/installation.md`.\n\n## Quick Start\n\n1. **Configure your Django project**:\n\n```python\n# settings.py\nINSTALLED_APPS = [\n # ... your other apps\n 'drf_to_mkdoc',\n]\n\n# Required for OpenAPI schema generation\nREST_FRAMEWORK = {\n 'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema', # Use our custom AutoSchema\n}\n\nSPECTACULAR_SETTINGS = {\n 'TITLE': 'Your API',\n 'DESCRIPTION': 'Your API description',\n 'VERSION': '1.0.0',\n\n}\n\nDRF_TO_MKDOC = {\n 'DJANGO_APPS': [\n 'users',\n 'products',\n 'orders',\n 'inventory',\n ],\n # Optional: Override default paths\n # 'DOCS_DIR': 'docs',\n # 'CONFIG_DIR': 'docs/configs',\n # 'MODEL_DOCS_FILE': 'docs/model-docs.json',\n # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',\n # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',\n}\n```\n\n2. **Create MkDocs configuration**: \n Copy the [`docs/mkdocs.yml`](docs/mkdocs.yml) file to your project root and customize it as needed.\n\n3. **Build documentation**:\n\n```bash\npython manage.py build_docs --settings=docs_settings\n```\n\n## Available Commands\n\n- `build_docs`: Build the complete documentation site with MkDocs\n- `build_endpoint_docs`: Build endpoint documentation from OpenAPI schema\n- `build_model_docs`: Build model documentation from model JSON data\n- `extract_model_data`: Extract model data from Django model introspection and save as JSON\n- `update_doc_schema`: Update the final schema by copying the documented schema\n\n## What you get\n\nSee a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.\n\n\n## How it works\n\nUnder 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.\n\n## Explore more\n\n- Customizing endpoint docs: `docs/customizing_endpoints.md`\n- Serving docs through Django (with permissions): `docs/serving_mkdocs_with_django.md`\n\n## Dependencies\n\n- Django >= 3.2, < 6.0\n- Django REST Framework >= 3.12, < 4.0\n- drf-spectacular >= 0.26.0\n- PyYAML >= 6.0\n- MkDocs >= 1.4.0\n- MkDocs Material >= 9.0.0\n- coreapi >= 2.3.0\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/Shayestehhs/drf-to-mkdoc.git\ncd drf-to-mkdoc\npip install -e \".[dev]\"\n```\n\n## Project Structure\n\n```\ndrf-to-mkdoc/\n\u251c\u2500\u2500 drf_to_mkdoc/\n\u2502 \u251c\u2500\u2500 conf/\n\u2502 \u2502 \u251c\u2500\u2500 defaults.py # Default configuration values\n\u2502 \u2502 \u2514\u2500\u2500 settings.py # Settings management\n\u2502 \u251c\u2500\u2500 management/\n\u2502 \u2502 \u2514\u2500\u2500 commands/\n\u2502 \u2502 \u251c\u2500\u2500 build_docs.py # Build MkDocs site\n\u2502 \u2502 \u251c\u2500\u2500 build_endpoint_docs.py # Build endpoint documentation\n\u2502 \u2502 \u251c\u2500\u2500 build_model_docs.py # Build model documentation\n\u2502 \u2502 \u251c\u2500\u2500 extract_model_data.py # Extract model data from Django\n\u2502 \u2502 \u2514\u2500\u2500 update_doc_schema.py # Schema updates\n\u2502 \u2514\u2500\u2500 utils/\n\u2502 \u251c\u2500\u2500 common.py # Shared utilities\n\u2502 \u251c\u2500\u2500 endpoint_generator.py # Endpoint documentation\n\u2502 \u251c\u2500\u2500 model_generator.py # Model documentation\n\u2502 \u2514\u2500\u2500 extractors/ # Query parameter extraction\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Recommendations\n\n### .gitignore Configuration\n\nTo avoid committing generated files to your repository, add the following to your `.gitignore` file:\n\n```gitignore\n# Documentation\n/docs/endpoints/\n/docs/models/\n/docs/configs/doc-schema.yaml\n\n# Build artifacts\n/site/\n```\n\nThis will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.\n\n### docs_settings.py Best Practices\n\nCreate a separate `docs_settings.py` file that inherits from your main settings:\n\n```python\n# docs_settings.py\nfrom .settings import *\n\nDRF_TO_MKDOC = {\n 'DJANGO_APPS': ['your_app1', 'your_app2'],\n}\n# Other doc settings...\n```\n\nThen use the `--settings` argument when running the build command:\n\n```bash\npython manage.py build_docs --settings=docs_settings\n```\n\n### Project Organization\n\n```\nyour-project/\n\u251c\u2500\u2500 settings.py # Main Django settings\n\u251c\u2500\u2500 docs_settings.py # Documentation-specific settings\n\u251c\u2500\u2500 mkdocs.yml # MkDocs configuration\n\u251c\u2500\u2500 docs/ # Generated documentation (gitignored)\n\u2514\u2500\u2500 site/ # Built site (gitignored)\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines. \nThis will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate Markdown API docs from Django/DRF OpenAPI schema for MkDocs",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/shayestehhs/drf-to-mkdoc/issues",
"Documentation": "https://github.com/shayestehhs/drf-to-mkdoc#readme",
"Homepage": "https://github.com/shayestehhs/drf-to-mkdoc",
"Repository": "https://github.com/shayestehhs/drf-to-mkdoc"
},
"split_keywords": [
"django",
" django-rest-framework",
" documentation",
" mkdocs",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6a341614d5ecb681d1eb4ba631ebb918f2d81b7cc5de393d46c59a361cef0ec0",
"md5": "c8e2eef0633749361f57e6c59d98f30d",
"sha256": "e210ee74ea1494940980bf878aed1dbbcb0a000f96b14a8f9d13c3b4a8f87657"
},
"downloads": -1,
"filename": "drf_to_mkdoc-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8e2eef0633749361f57e6c59d98f30d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 83308,
"upload_time": "2025-09-10T17:11:27",
"upload_time_iso_8601": "2025-09-10T17:11:27.460663Z",
"url": "https://files.pythonhosted.org/packages/6a/34/1614d5ecb681d1eb4ba631ebb918f2d81b7cc5de393d46c59a361cef0ec0/drf_to_mkdoc-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "92119ccd3af0179829fdf52992151a0906371b239bc4937470232ded9134cd1c",
"md5": "a45a5f11b11a16d6c5fd6c783e5fc69e",
"sha256": "4a8857f0dfbb07aa7a9e0e90e9999ab61df47a5bd38cba145e9d79c9b4d54af9"
},
"downloads": -1,
"filename": "drf_to_mkdoc-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "a45a5f11b11a16d6c5fd6c783e5fc69e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70956,
"upload_time": "2025-09-10T17:11:28",
"upload_time_iso_8601": "2025-09-10T17:11:28.716752Z",
"url": "https://files.pythonhosted.org/packages/92/11/9ccd3af0179829fdf52992151a0906371b239bc4937470232ded9134cd1c/drf_to_mkdoc-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 17:11:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shayestehhs",
"github_project": "drf-to-mkdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "drf-to-mkdoc"
}
JSON
