drf-to-mkdoc 0.2.1__tar.gz → 0.2.2__tar.gz

{drf_to_mkdoc-0.2.1 → drf_to_mkdoc-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.2.1
+Version: 0.2.2
 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>

{drf_to_mkdoc-0.2.1 → drf_to_mkdoc-0.2.2}/drf_to_mkdoc/conf/settings.py

@@ -138,8 +138,6 @@ class DRFToMkDocSettings:
         self._validate_range(key, value)
         self._validate_dir(key, value)
 
-        if value is None:
-            raise AttributeError(f"Invalid DRF_TO_MKDOC setting: '{key}'")
         return value
 
     def __getattr__(self, key):

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/detail/base.html

@@ -0,0 +1,33 @@
+<!-- inject CSS and JS directly -->
+{% load custom_filters %}
+{% for stylesheet in stylesheets %}
+<link rel="stylesheet" href="{% static_with_prefix stylesheet prefix_path %}">
+{% endfor %}
+{% for script in scripts %}
+<script src="{% static_with_prefix script prefix_path %}" defer></script>
+{% endfor %}
+
+# {{ method|upper }} {{ path }}
+
+{{ method|format_method_badge|safe }} `{{ path }}`
+
+**View class:** {{ viewset_name }}
+
+{% if summary %}
+## Overview
+
+{{ summary }}
+{% endif %}
+
+{% if operation_id %}
+**Operation ID:** `{{ operation_id }}`
+{% endif %}
+
+{% if description %}
+{{ description|safe }}
+{% endif %}
+
+{% include "endpoints/detail/path_parameters.html" %}
+{% include "endpoints/detail/query_parameters.html" %}
+{% include "endpoints/detail/request_body.html" %}
+{% include "endpoints/detail/responses.html" %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/detail/path_parameters.html

@@ -0,0 +1,8 @@
+{% if path_params %}
+## Path Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+{% for param in path_params %}| `{{ param.name }}` | `{{ param.schema.type|default:"string" }}` | {{ param.required|yesno:"Yes,No" }} | {{ param.description }} |{% endfor %}
+{% endif %}
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/detail/query_parameters.html

@@ -0,0 +1,43 @@
+{% comment %}
+Check if any query parameter fields have content
+{% endcomment %}
+
+{% if query_parameters.filter_fields or query_parameters.search_fields or query_parameters.ordering_fields or query_parameters.filter_backends or query_parameters.pagination_fields %}
+## Query Parameters
+
+{% if query_parameters.filter_fields %}
+### Filter Fields
+{% for field in query_parameters.filter_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.search_fields %}
+### Search Fields
+{% for field in query_parameters.search_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.ordering_fields %}
+### Ordering Fields
+{% for field in query_parameters.ordering_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.filter_backends %}
+### Filter Backends
+{% for backend in query_parameters.filter_backends %}
+- `{{ backend }}`
+{% endfor %}
+{% endif %}
+
+{% if query_parameters.pagination_fields %}
+### Pagination Fields
+{% for field in query_parameters.pagination_fields %}
+- `{{ field }}`
+{% endfor %}
+{% endif %}
+
+{% endif %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/detail/request_body.html

@@ -0,0 +1,10 @@
+{% load custom_filters %}
+
+{% if request_body %}
+## Request Body
+
+{% if request_example %}
+{{ request_example|format_json }}
+{% endif %}
+
+{% endif %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/detail/responses.html

@@ -0,0 +1,18 @@
+{% load custom_filters %}
+
+{% if responses %}
+## Responses
+
+{% for response in responses %}
+### {{ response.status_code }}
+
+{% if response.description %}
+{{ response.description }}
+{% endif %}
+
+{% if response.example %}
+{{ response.example|format_json }}
+{% endif %}
+
+{% endfor %}
+{% endif %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/base.html

@@ -0,0 +1,23 @@
+# API Endpoints
+
+<style>
+{% for stylesheet in stylesheets %}
+@import url("{{ stylesheet|safe }}");
+{% endfor %}
+</style>
+
+{% for script in scripts %}
+<script src="{{ script|safe }}" defer></script>
+{% endfor %}
+
+<div class="main-content">
+    {% include "endpoints/list/filter_section.html" %}
+    {% for app_name, endpoints in endpoints_by_app.items %}
+        <h2>{{ app_name|title }}</h2>
+        <div class="endpoints-grid">
+            {% for endpoint in endpoints %}
+                {% include "endpoints/list/endpoint_card.html" %}
+            {% endfor %}
+        </div>
+    {% endfor %}
+</div>

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/endpoint_card.html

@@ -0,0 +1,18 @@
+{% load custom_filters %}
+<a href="{{ endpoint.link_url }}" class="endpoint-card"
+    data-method="{{ endpoint.method|lower }}"
+    data-path="{{ endpoint.path|lower }}"
+    data-app="{{ app_name|lower }}"
+    data-auth="{{ endpoint.auth_required|default:'false'|lower }}"
+    data-pagination="{{ endpoint.pagination_support|default:'false'|lower }}"
+    data-search="{{ endpoint.view_class.search_fields|default:''|length|yesno:'true,false'|lower }}"
+    data-ordering="{{ endpoint.ordering_support|default:'false'|lower }}"
+    data-models="{{ endpoint.related_models|default:''|join:' '|lower }}"
+    data-roles="{{ endpoint.permission_roles|default:''|join:' '|lower }}"
+    data-content-type="{{ endpoint.content_type|default:''|lower }}"
+    data-tags="{{ endpoint.tags|default:''|join:' '|lower }}"
+    data-schema="{{ endpoint.schema_fields|default:''|join:' '|lower }}"
+    data-params="{{ endpoint.query_parameters|default:''|join:' '|lower }}">
+    <span class="method-badge method-{{ endpoint.method|lower }}">{{ endpoint.method }}</span>
+    <span class="endpoint-path">{{ endpoint.path }}</span>
+</a>

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/filter_section.html

@@ -0,0 +1,16 @@
+<div class="filter-sidebar collapsed" id="filterSidebar">
+    <h3 class="filter-title">🔍 Filters</h3>
+    <div class="filter-grid">
+        {% for filter_key in active_filters %}
+            {% include "endpoints/list/filters/"|add:filter_key|add:".html" %}
+        {% endfor %}
+    </div>
+
+    <div class="filter-actions">
+        <button class="filter-apply" onclick="applyFilters()">Apply</button>
+        <button class="filter-clear" onclick="clearFilters()">Clear</button>
+    </div>
+
+    <div class="filter-results">Showing 0 endpoints</div>
+</div>
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/filters/app.html

@@ -0,0 +1,8 @@
+<div class="filter-group">
+    <label class="filter-label">Django App</label>
+    <select id="filter-app" class="filter-select">
+        <option value="">All</option>
+        <!-- Dynamically filled -->
+    </select>
+</div>
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/filters/method.html

@@ -0,0 +1,12 @@
+<div class="filter-group">
+    <label class="filter-label">HTTP Method</label>
+    <select id="filter-method" class="filter-select">
+        <option value="">All</option>
+        <option value="get">GET</option>
+        <option value="post">POST</option>
+        <option value="put">PUT</option>
+        <option value="patch">PATCH</option>
+        <option value="delete">DELETE</option>
+    </select>
+</div>
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/filters/path.html

@@ -0,0 +1,5 @@
+<div class="filter-group">
+    <label class="filter-label">Endpoint Path</label>
+    <input type="text" id="filter-path" class="filter-input" placeholder="Search path...">
+</div>
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/endpoints/list/filters/search.html

@@ -0,0 +1,9 @@
+<div class="filter-group">
+    <label class="filter-label">Search Support</label>
+    <select id="filter-search" class="filter-select">
+        <option value="">All</option>
+        <option value="true">Yes</option>
+        <option value="false">No</option>
+    </select>
+</div>
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/base.html

@@ -0,0 +1,34 @@
+# {{ name }}
+
+<!-- inject CSS directly -->
+{% for stylesheet in stylesheets %}
+<link rel="stylesheet" href="{{ stylesheet }}">
+{% endfor %}
+
+**App:** {{ app_label }}
+
+**Table:** `{{ table_name }}`
+
+## Description
+
+{{ description }}
+
+{% if fields %}
+{% include "model_detail/fields.html" with fields=fields %}
+{% endif %}
+
+{% if has_choices %}
+{% include "model_detail/choices.html" with fields=fields %}
+{% endif %}
+
+{% if relationships %}
+{% include "model_detail/relationships.html" with relationships=relationships %}
+{% endif %}
+
+{% if methods %}
+{% include "model_detail/methods.html" with methods=methods %}
+{% endif %}
+
+{% if meta_options %}
+{% include "model_detail/meta.html" with meta_options=meta_options %}
+{% endif %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/choices.html

@@ -0,0 +1,12 @@
+{% load custom_filters %}
+## Choices
+
+{% for field_name, field_info in fields.items %}{% if field_info.choices %}
+### {{ field_name }} Choices
+
+| Label | Value |
+|-------|-------|
+{% for choice in field_info.choices %}| {{ choice.display }} | `{{ choice.value }}` |
+{% endfor %}
+
+{% endif %}{% endfor %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/fields.html

@@ -0,0 +1,11 @@
+{% load custom_filters %}
+## Fields
+
+| Field | Type | Description | Extra |
+|-------|------|-------------|-------|
+{% for field_name, field_info in fields.items %}{% with field_type=field_info.type|default:"Unknown" %}{% if field_type == "TextField" %}| `{{ field_name }}` | TextField | {{ field_name }} | {% if field_info.max_length %}max_length={{ field_info.max_length }}{% endif %} |
+{% elif field_type == "BigAutoField" %}| `{{ field_name }}` | BigAutoField | ID | {% if field_info.blank %}blank=True{% endif %}{% if field_info.unique %}, unique=True{% endif %}{% if field_info.primary_key %}, primary_key=True{% endif %} |
+{% elif field_type == "CharField" %}| `{{ field_name }}` | CharField | {{ field_name }} | {% if field_info.max_length %}max_length={{ field_info.max_length }}{% endif %}{% if field_info.null %}, null=True{% endif %}{% if field_info.blank %}, blank=True{% endif %} |
+{% elif field_type == "ForeignKey" %}| `{{ field_name }}` | ForeignKey | {{ field_info.field_specific.to|default:"" }} | |
+{% else %}| `{{ field_name }}` | {{ field_type }} | {{ field_name }} | {{ field_info|format_field_extra }} |
+{% endif %}{% endwith %}{% endfor %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/meta.html

@@ -0,0 +1,6 @@
+## Meta Options
+
+{% for option, value in meta_options.items %}
+- **{{ option }}:** {{ value }}
+{% endfor %}
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/methods.html

@@ -0,0 +1,9 @@
+## Methods
+
+{% for method in methods %}
+### `{{ method.name }}()`
+
+{{ method.docstring|default:"No documentation available." }}
+
+{% endfor %}
+

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/model_detail/relationships.html

@@ -0,0 +1,8 @@
+{% load custom_filters %}
+## Relationships
+
+| Field | Type | Related Model |
+|-------|------|---------------|
+{% for field_name, field_info in relationships.items %}{% with field_type=field_info.type|default:"Unknown" %}{% if field_info.field_specific.to %}| `{{ field_name }}` | {{ field_type }} | {% if "." in field_info.field_specific.to %}[{{ field_info.field_specific.to|cut:"." }}](../{{ field_info.field_specific.to|cut:"." }}/{% else %}[{{ field_info.field_specific.to }}]({{ field_info.field_specific.to|lower }}/{% endif %} |
+{% endif %}{% endwith %}{% endfor %}{% for rel_name, rel_info in relationships.items %}| `{{ rel_name }}` | {{ rel_info.type|default:"Unknown" }} | [{{ rel_info.verbose_name|capfirst }}](../../{{ rel_info.app_label }}/{{ rel_info.table_name }}/) |
+{% endfor %}

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templates/models_index.html

@@ -0,0 +1,24 @@
+{% load custom_filters %}
+# Django Models
+
+This section contains documentation for all Django models in the system, organized by Django application.
+
+<!-- inject CSS directly -->
+{% for css in stylesheets %}
+<link rel="stylesheet" href="{{ css }}">
+{% endfor %}
+
+<div class="models-container">
+{% for app_name, models in sorted_models %}
+    <div class="app-header">{{ app_name|title|cut:"_"|safe }}</div>
+    <div class="app-description">{{ app_descriptions|get_item:app_name }}</div>
+
+    <div class="model-cards">
+    {% for verbose_name, table_name in models %}
+        <a href="{{ app_name|urlencode }}/{{ table_name|urlencode }}/" class="model-card">{{ verbose_name }}</a>
+    {% endfor %}
+    </div>
+{% endfor %}
+</div>
+
+Each model page contains detailed field documentation, method signatures, and relationships to other models.

drf_to_mkdoc-0.2.2/drf_to_mkdoc/templatetags/custom_filters.py

@@ -0,0 +1,116 @@
+import html
+import json
+
+from django import template
+from django.templatetags.static import static as django_static
+from django.utils.safestring import mark_safe
+
+from drf_to_mkdoc.utils.commons.operation_utils import (
+    format_method_badge as format_method_badge_util,
+)
+
+register = template.Library()
+
+
+@register.filter
+def is_foreign_key(field_type):
+    return field_type in ["ForeignKey", "OneToOneField"]
+
+
+@register.simple_tag
+def static_with_prefix(path, prefix=""):
+    """Add prefix to static path"""
+    return django_static(prefix + path)
+
+
+@register.filter
+def format_method_badge(method):
+    """Format HTTP method as badge"""
+    return format_method_badge_util(method)
+
+
+@register.filter
+def get_display_name(field_name, field_type):
+    if field_type in ["ForeignKey", "OneToOneField"]:
+        return f"{field_name}_id"
+    return field_name
+
+
+@register.filter
+def split(value, delimiter=","):
+    return value.split(delimiter)
+
+
+@register.filter
+def cut(value, arg):
+    return value.split(arg)[1] if "." in value else value
+
+
+@register.filter
+def get_item(dictionary, key):
+    return dictionary.get(key, "")
+
+
+@register.filter
+def format_field_type(field_info):
+    field_type = field_info.get("type", "")
+    if field_type == "ForeignKey":
+        return f"ForeignKey | {field_info.get('field_specific', {}).get('to', '')}"
+    if field_type == "CharField":
+        max_length = field_info.get("max_length", "")
+        return f"CharField | {field_info.get('verbose_name', '')} | max_length={max_length}"
+    return field_type
+
+
+@register.filter
+def format_field_extra(field_info):
+    extras = []
+    if field_info.get("null"):
+        extras.append("null=True")
+    if field_info.get("blank"):
+        extras.append("blank=True")
+    if field_info.get("unique"):
+        extras.append("unique=True")
+    if field_info.get("primary_key"):
+        extras.append("primary_key=True")
+    if field_info.get("max_length"):
+        extras.append(f"max_length={field_info['max_length']}")
+    return ", ".join(extras)
+
+
+@register.filter
+def yesno(value, arg=None):
+    """
+    Given a string mapping values for true, false and (optionally) None,
+    return one of those strings according to the value.
+    """
+    if arg is None:
+        arg = "yes,no,maybe"
+    bits = arg.split(",")
+    if len(bits) < 2:
+        return value  # Invalid arg.
+    try:
+        yes, no, maybe = bits
+    except ValueError:
+        yes, no, maybe = bits[0], bits[1], bits[1]
+
+    if value is None:
+        return maybe
+    if value:
+        return yes
+    return no
+
+
+@register.filter
+def format_json(value):
+    if isinstance(value, str):
+        value = html.unescape(value)
+        try:
+            parsed = json.loads(value)
+            value = json.dumps(parsed, indent=2)
+        except (json.JSONDecodeError, TypeError):
+            pass
+    elif isinstance(value, dict | list):
+        value = json.dumps(value, indent=2)
+
+    return mark_safe(value)  # noqa: S308