Metadata-Version: 2.4
Name: django-api-readme
Version: 0.1.0
Summary: Generate clean API Markdown documentation natively from Django URLs and DRF serializers.
Author: CodeWithClinton
License: MIT
Project-URL: Homepage, https://github.com/CodeWithClinton/django-api-readme
Project-URL: Repository, https://github.com/CodeWithClinton/django-api-readme.git
Project-URL: Bug Tracker, https://github.com/CodeWithClinton/django-api-readme/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14.0; extra == "drf"
Dynamic: license-file

# django-api-readme

A production-ready Python package that natively integrates with Django and Django REST Framework (DRF) to automatically discover and map your API routes into clean, structured Markdown documentation.

It reads your configuration dynamically and supports optional payload inspection for DRF serializers without any hard dependencies.

## Installation

There are two ways to install this package depending on your environment:

**1. Standard Installation**
```bash
pip install django-api-readme
```
*Use this if you are either **NOT** using Django REST Framework (DRF), OR if you **already have** DRF installed in your active project. (If DRF is already present, our package securely detects it at runtime and beautifully documents your endpoints automatically!)*

**2. Installation alongside DRF**
```bash
pip install django-api-readme[drf]
```
*Use this strictly as a shortcut if you are building an API inside a completely blank space and want `pip` to automatically download and install `djangorestframework` for you seamlessly alongside this package.*

## Usage

**1. Register the Application**  
Add `django_api_readme` to your `INSTALLED_APPS` inside `settings.py`:
```python
INSTALLED_APPS = [
    # ...
    'django_api_readme',
]
```

**2. Insert the Markers**  
Add the following template boundaries into your target Markdown file (e.g., `README.md`). The generator will safely inject the documentation directly between them!
```markdown
<!-- API_DOCS_START -->
<!-- API_DOCS_END -->
```

**3. Run the Generator**  
Execute the native management command from your terminal to scan your codebase and overwrite the marker bounds automatically:
```bash
python manage.py generate_api_docs --output README.md --include /api/
```

**Command Breakdown:**
* `generate_api_docs`: Invokes the custom Django management command bundled with this package.
* `--output README.md`: *(Optional)* Specifies the target Markdown file where the API documentation bounds will be injected. Defaults to `README.md`.
* `--include /api/`: *(Optional)* Filters the discovered URLs so that only endpoints starting with `/api/` are documented. This gracefully ignores admin panels or frontend routing!

---

## Example Output

This is a live example of the clean formatting the management command injects structurally:

### `GET, POST` /api/v1/students/

List all enrolled students or create a newly enrolled student.

- **View:** `StudentViewSet` | **Name:** `student-list`

**Request Schema**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | `string` | **Yes** | Given name. |
| `email` | `string (email)` | **Yes** | School email suffix required. |
| `gpa` | `float` | No | *(Read-only)* Automatically calculated. |

---

<!-- API_DOCS_START -->
<!-- API_DOCS_END -->
