# 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**:
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
```
## 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
│ │ ├── 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.
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/e7/45/c71728259513938c6336c06bfd23f87af0d6296abad339833e861a1805da/drf_to_mkdoc-0.1.9.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_spectacular.openapi.AutoSchema',\n}\n\nSPECTACULAR_SETTINGS = {\n 'TITLE': 'Your API',\n 'DESCRIPTION': 'Your API description',\n 'VERSION': '1.0.0',\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## 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## 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 generate_docs.py # Main documentation generator\n\u2502 \u2502 \u251c\u2500\u2500 generate_model_docs.py # Model documentation\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.1.9",
"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": "022811251db30ec045e72b230ef6a313b3da561e1ea8f73bf158820e6af0bb13",
"md5": "aad24226d0bf3656cc918ad1ada5073a",
"sha256": "dd5c4e54d08554a276e4284cfe4d11f89bf4c6272abcf9fbad3c9f4bd8ac2e8d"
},
"downloads": -1,
"filename": "drf_to_mkdoc-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aad24226d0bf3656cc918ad1ada5073a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 59144,
"upload_time": "2025-08-17T21:14:18",
"upload_time_iso_8601": "2025-08-17T21:14:18.645872Z",
"url": "https://files.pythonhosted.org/packages/02/28/11251db30ec045e72b230ef6a313b3da561e1ea8f73bf158820e6af0bb13/drf_to_mkdoc-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e745c71728259513938c6336c06bfd23f87af0d6296abad339833e861a1805da",
"md5": "1f02587d3fba1831f6a710a33969a314",
"sha256": "87c00a636b641cb8297489a4649f7455efff307f1c34219c234ee0123d956021"
},
"downloads": -1,
"filename": "drf_to_mkdoc-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "1f02587d3fba1831f6a710a33969a314",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 52251,
"upload_time": "2025-08-17T21:14:20",
"upload_time_iso_8601": "2025-08-17T21:14:20.023337Z",
"url": "https://files.pythonhosted.org/packages/e7/45/c71728259513938c6336c06bfd23f87af0d6296abad339833e861a1805da/drf_to_mkdoc-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 21:14:20",
"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
