django-cfg 1.4.108__py3-none-any.whl → 1.4.110__py3-none-any.whl

django_cfg/modules/django_admin/config/field_config.py

@@ -254,3 +254,90 @@ class ImageField(FieldConfig):
             config['caption_template'] = self.caption_template
         config['alt_text'] = self.alt_text
         return config
+
+
+class MarkdownField(FieldConfig):
+    """
+    Markdown documentation widget configuration.
+
+    Renders markdown content from field value or external file with beautiful styling.
+    Auto-detects whether content is a file path or markdown string.
+
+    Examples:
+        # From model field (markdown string)
+        MarkdownField(
+            name="description",
+            title="Documentation",
+            collapsible=True
+        )
+
+        # From file path field
+        MarkdownField(
+            name="docs_path",
+            title="User Guide",
+            collapsible=True,
+            default_open=True
+        )
+
+        # Static file (same for all objects)
+        MarkdownField(
+            name="static_doc",  # method that returns file path
+            title="API Documentation",
+            source_file="docs/api.md",  # relative to app root
+            max_height="500px"
+        )
+
+        # Dynamic markdown with custom title
+        MarkdownField(
+            name="get_help_text",  # method that generates markdown
+            title="Help",
+            collapsible=True,
+            enable_plugins=True
+        )
+    """
+
+    ui_widget: Literal["markdown"] = "markdown"
+
+    # Display options
+    collapsible: bool = Field(True, description="Wrap in collapsible details/summary")
+    default_open: bool = Field(False, description="Open by default if collapsible")
+    max_height: Optional[str] = Field("500px", description="Max height with scrolling (e.g., '500px', None for no limit)")
+
+    # Content source
+    source_file: Optional[str] = Field(
+        None,
+        description="Static file path relative to app root (e.g., 'docs/api.md')"
+    )
+    source_field: Optional[str] = Field(
+        None,
+        description="Alternative field name for content (defaults to 'name' field)"
+    )
+
+    # Markdown options
+    enable_plugins: bool = Field(
+        True,
+        description="Enable mistune plugins (tables, strikethrough, task lists, etc.)"
+    )
+
+    # Custom icon for collapsible header
+    header_icon: Optional[str] = Field(
+        "description",
+        description="Material icon for collapsible header"
+    )
+
+    def get_widget_config(self) -> Dict[str, Any]:
+        """Extract markdown widget configuration."""
+        config = super().get_widget_config()
+        config['collapsible'] = self.collapsible
+        config['default_open'] = self.default_open
+        config['max_height'] = self.max_height
+        config['enable_plugins'] = self.enable_plugins
+
+        if self.source_file is not None:
+            config['source_file'] = self.source_file
+        if self.source_field is not None:
+            config['source_field'] = self.source_field
+        if self.header_icon is not None:
+            config['header_icon'] = self.header_icon
+
+        return config

django_cfg/modules/django_admin/templates/django_admin/change_form_docs.html

@@ -0,0 +1,23 @@
+{% extends "admin/change_form.html" %}
+{% load static %}
+
+{% block field_sets %}
+    {# Markdown documentation before fieldsets #}
+    {% if adminform.model_admin.documentation_config %}
+        {% with config=adminform.model_admin.documentation_config %}
+            {% if config.show_on_changeform %}
+                <div class="mb-6">
+                    {% include "django_admin/markdown_docs_block.html" with
+                        content=config.content
+                        title=config.title
+                        collapsible=config.collapsible
+                        default_open=config.default_open
+                        max_height=config.max_height
+                    %}
+                </div>
+            {% endif %}
+        {% endwith %}
+    {% endif %}
+
+    {{ block.super }}
+{% endblock %}

django_cfg/modules/django_admin/templates/django_admin/change_list_docs.html

@@ -0,0 +1,23 @@
+{% extends "admin/change_list.html" %}
+{% load static %}
+
+{% block content_title %}
+    {{ block.super }}
+
+    {# Markdown documentation above the list #}
+    {% if cl.model_admin.documentation_config %}
+        {% with config=cl.model_admin.documentation_config %}
+            {% if config.show_on_changelist %}
+                <div class="mt-4">
+                    {% include "django_admin/markdown_docs_block.html" with
+                        content=config.content
+                        title=config.title
+                        collapsible=config.collapsible
+                        default_open=config.default_open
+                        max_height=config.max_height
+                    %}
+                </div>
+            {% endif %}
+        {% endwith %}
+    {% endif %}
+{% endblock %}

django_cfg/modules/django_admin/templates/django_admin/documentation_block.html

@@ -0,0 +1,297 @@
+{% load static %}
+{# Multi-Section Markdown Documentation Block with Management Commands - Used with unfold hooks #}
+
+{% if documentation_config and documentation_sections or management_commands %}
+<div class="mb-6">
+    <div class="{% if not is_popup %}max-w-full{% endif %}">
+        {# Main documentation container with unfold semantic classes #}
+        <div class="bg-base-50 dark:bg-base-950 border border-base-200 dark:border-base-700 rounded-default shadow-xs overflow-hidden">
+
+            {# Header with semantic font colors #}
+            <div class="px-5 py-4 border-b border-base-200 dark:border-base-800 bg-base-100 dark:bg-base-900">
+                <div class="flex items-center gap-3">
+                    <span class="material-symbols-outlined text-xl text-primary-600 dark:text-primary-400">description</span>
+                    <h2 class="text-base font-semibold text-font-important-light dark:text-font-important-dark m-0">
+                        {{ documentation_config.title }}
+                    </h2>
+                    {% if documentation_sections %}
+                    <span class="ml-auto text-xs font-medium text-font-subtle-light dark:text-font-subtle-dark px-2.5 py-1 bg-base-100 dark:bg-base-800 rounded-full">
+                        {{ documentation_sections|length }} section{{ documentation_sections|length|pluralize }}
+                    </span>
+                    {% endif %}
+                </div>
+            </div>
+
+            {# Management Commands Section (if any) #}
+            {% if management_commands %}
+            <details class="group border-b border-base-200 dark:border-base-800">
+                <summary class="cursor-pointer px-5 py-3.5 bg-white dark:bg-base-900 hover:bg-base-700/[.04] dark:hover:bg-white/[.04] transition-all duration-200 flex items-center gap-3 select-none list-none">
+                    {# Terminal icon #}
+                    <span class="material-symbols-outlined text-base text-font-default-light dark:text-font-default-dark group-open:rotate-90 group-open:text-primary-600 dark:group-open:text-primary-400 transition-all duration-200">
+                        terminal
+                    </span>
+
+                    {# Title #}
+                    <span class="text-sm font-medium text-font-default-light dark:text-font-default-dark flex-1">
+                        Management Commands
+                    </span>
+
+                    {# Badge #}
+                    <span class="text-xs font-medium text-font-subtle-light dark:text-font-subtle-dark px-2.5 py-1 bg-primary-50 dark:bg-primary-900/20 text-primary-600 dark:text-primary-400 rounded-full">
+                        {{ management_commands|length }} command{{ management_commands|length|pluralize }}
+                    </span>
+
+                    {# Expand/collapse hint #}
+                    <span class="text-xs text-font-subtle-light dark:text-font-subtle-dark group-open:hidden">
+                        Click to expand
+                    </span>
+                    <span class="text-xs text-font-subtle-light dark:text-font-subtle-dark hidden group-open:inline">
+                        Click to collapse
+                    </span>
+                </summary>
+
+                {# Commands list #}
+                <div class="px-5 py-4 bg-white dark:bg-base-900">
+                    <div class="flex flex-col gap-3">
+                        {% for cmd in management_commands %}
+                        <div class="border border-base-200 dark:border-base-700 rounded-default p-4 bg-base-50 dark:bg-base-950 hover:border-primary-300 dark:hover:border-primary-700 transition-colors duration-200">
+                            {# Command name #}
+                            <div class="flex items-start gap-3 mb-2">
+                                <span class="material-symbols-outlined text-sm text-primary-600 dark:text-primary-400 mt-0.5">code</span>
+                                <div class="flex-1 min-w-0">
+                                    <code class="text-sm font-mono font-semibold text-font-important-light dark:text-font-important-dark">
+                                        python manage.py {{ cmd.name }}
+                                    </code>
+                                    {% if cmd.help %}
+                                    <p class="text-xs text-font-default-light dark:text-font-default-dark mt-1">
+                                        {{ cmd.help }}
+                                    </p>
+                                    {% endif %}
+                                </div>
+                            </div>
+
+                            {# Arguments #}
+                            {% if cmd.arguments %}
+                            <div class="mt-3 pt-3 border-t border-base-200 dark:border-base-700">
+                                <div class="text-xs font-medium text-font-subtle-light dark:text-font-subtle-dark mb-2">Arguments:</div>
+                                <div class="space-y-1.5">
+                                    {% for arg in cmd.arguments %}
+                                    <div class="flex items-start gap-2 text-xs">
+                                        <code class="font-mono text-primary-600 dark:text-primary-400 font-medium">{{ arg.name }}</code>
+                                        {% if arg.required %}
+                                        <span class="px-1.5 py-0.5 bg-red-50 dark:bg-red-900/20 text-red-600 dark:text-red-400 rounded text-[10px] font-medium">required</span>
+                                        {% endif %}
+                                        {% if arg.help %}
+                                        <span class="text-font-subtle-light dark:text-font-subtle-dark">- {{ arg.help }}</span>
+                                        {% endif %}
+                                        {% if arg.default %}
+                                        <span class="text-font-subtle-light dark:text-font-subtle-dark ml-auto">default: <code class="text-[10px]">{{ arg.default }}</code></span>
+                                        {% endif %}
+                                    </div>
+                                    {% endfor %}
+                                </div>
+                            </div>
+                            {% endif %}
+                        </div>
+                        {% endfor %}
+                    </div>
+                </div>
+            </details>
+            {% endif %}
+
+            {# Documentation Sections #}
+            {% if documentation_sections %}
+            <div class="divide-y divide-base-200 dark:divide-base-800">
+                {% for section in documentation_sections %}
+                {% if documentation_config.collapsible %}
+                {# Collapsible section #}
+                <details class="group"{% if section.default_open %} open{% endif %}>
+                    <summary class="cursor-pointer px-5 py-3.5 bg-white dark:bg-base-900 hover:bg-base-700/[.04] dark:hover:bg-white/[.04] transition-all duration-200 flex items-center gap-3 select-none list-none">
+                        {# Chevron icon #}
+                        <span class="material-symbols-outlined text-base text-font-default-light dark:text-font-default-dark group-open:rotate-90 group-open:text-primary-600 dark:group-open:text-primary-400 transition-all duration-200">
+                            chevron_right
+                        </span>
+
+                        {# Section title #}
+                        <span class="text-sm font-medium text-font-default-light dark:text-font-default-dark flex-1">
+                            {{ section.title }}
+                        </span>
+
+                        {# Expand/collapse hint #}
+                        <span class="text-xs text-font-subtle-light dark:text-font-subtle-dark group-open:hidden">
+                            Click to expand
+                        </span>
+                        <span class="text-xs text-font-subtle-light dark:text-font-subtle-dark hidden group-open:inline">
+                            Click to collapse
+                        </span>
+                    </summary>
+
+                    {# Section content #}
+                    <div class="p-5 bg-white dark:bg-base-900">
+                        <div class="border border-base-200 dark:border-base-700 rounded-default p-4 bg-white dark:bg-base-950 prose prose-sm dark:prose-invert max-w-none overflow-auto"
+                             {% if documentation_config.max_height %}style="max-height: {{ documentation_config.max_height }};"{% endif %}>
+                            {{ section.content|safe }}
+                        </div>
+                    </div>
+                </details>
+                {% else %}
+                {# Non-collapsible section #}
+                <div class="bg-white dark:bg-base-900">
+                    {% if section.title != documentation_config.title %}
+                    <div class="px-5 py-3 bg-base-50 dark:bg-base-950 border-b border-base-200 dark:border-base-800">
+                        <h3 class="text-sm font-medium text-font-important-light dark:text-font-important-dark m-0">
+                            {{ section.title }}
+                        </h3>
+                    </div>
+                    {% endif %}
+                    <div class="p-5">
+                        <div class="border border-base-200 dark:border-base-700 rounded-default p-4 bg-white dark:bg-base-950 prose prose-sm dark:prose-invert max-w-none overflow-auto"
+                             {% if documentation_config.max_height %}style="max-height: {{ documentation_config.max_height }};"{% endif %}>
+                            {{ section.content|safe }}
+                        </div>
+                    </div>
+                </div>
+                {% endif %}
+                {% endfor %}
+            </div>
+            {% endif %}
+        </div>
+    </div>
+</div>
+
+{# Enhanced dark mode prose styles with unfold semantic colors #}
+<style>
+    /* Unfold semantic dark mode prose styles */
+    .dark .prose-invert {
+        --tw-prose-body: rgb(var(--color-base-300));
+        --tw-prose-headings: rgb(var(--color-base-100));
+        --tw-prose-lead: rgb(var(--color-base-400));
+        --tw-prose-links: rgb(96 165 250);
+        --tw-prose-bold: rgb(var(--color-base-100));
+        --tw-prose-counters: rgb(var(--color-base-400));
+        --tw-prose-bullets: rgb(var(--color-base-500));
+        --tw-prose-hr: rgb(var(--color-base-700));
+        --tw-prose-quotes: rgb(var(--color-base-100));
+        --tw-prose-quote-borders: rgb(var(--color-base-700));
+        --tw-prose-captions: rgb(var(--color-base-400));
+        --tw-prose-code: rgb(var(--color-base-100));
+        --tw-prose-pre-code: rgb(var(--color-base-200));
+        --tw-prose-pre-bg: rgb(var(--color-base-950));
+        --tw-prose-th-borders: rgb(var(--color-base-700));
+        --tw-prose-td-borders: rgb(var(--color-base-700));
+    }
+
+    /* Light mode pre blocks */
+    .prose pre {
+        background-color: rgb(249, 250, 251) !important;
+        border: 1px solid rgb(229, 231, 235) !important;
+        color: rgb(17, 24, 39) !important;
+    }
+
+    .prose code {
+        background-color: rgb(243, 244, 246) !important;
+        color: rgb(17, 24, 39) !important;
+        padding: 0.125rem 0.25rem;
+        border-radius: 0.25rem;
+        font-size: 0.875em;
+    }
+
+    .prose pre code {
+        background-color: transparent !important;
+        padding: 0;
+        color: inherit !important;
+    }
+
+    /* Dark mode pre blocks */
+    .dark .prose-invert pre {
+        background-color: rgb(3, 7, 18) !important;
+        border: 1px solid rgb(55, 65, 81) !important;
+        color: rgb(229, 231, 235) !important;
+    }
+
+    .dark .prose-invert code {
+        background-color: rgb(31, 41, 55) !important;
+        color: rgb(243, 244, 246) !important;
+        padding: 0.125rem 0.25rem;
+        border-radius: 0.25rem;
+        font-size: 0.875em;
+    }
+
+    .dark .prose-invert pre code {
+        background-color: transparent !important;
+        padding: 0;
+        color: inherit !important;
+    }
+
+    /* Tables with semantic colors */
+    .dark .prose-invert table {
+        border-color: rgb(var(--color-base-700));
+    }
+
+    .dark .prose-invert thead {
+        border-bottom-color: rgb(var(--color-base-700));
+        background-color: rgb(var(--color-base-800));
+    }
+
+    .dark .prose-invert th,
+    .dark .prose-invert td {
+        border-color: rgb(var(--color-base-700));
+    }
+
+    .dark .prose-invert tbody tr {
+        border-bottom-color: rgb(var(--color-base-700));
+    }
+
+    .dark .prose-invert tbody tr:hover {
+        background-color: rgb(var(--color-base-800));
+    }
+
+    /* Links */
+    .dark .prose-invert a {
+        color: rgb(96 165 250) !important;
+    }
+
+    .dark .prose-invert a:hover {
+        color: rgb(147 197 253) !important;
+    }
+
+    /* Blockquotes with semantic colors */
+    .dark .prose-invert blockquote {
+        border-left-color: rgb(var(--color-base-700));
+        background-color: rgb(var(--color-base-800));
+        padding: 1rem;
+        border-radius: 0.375rem;
+    }
+
+    /* Lists */
+    .dark .prose-invert ul > li::marker,
+    .dark .prose-invert ol > li::marker {
+        color: rgb(var(--color-base-500));
+    }
+
+    /* Horizontal rules */
+    .dark .prose-invert hr {
+        border-color: rgb(var(--color-base-700));
+    }
+
+    /* Custom scrollbar with semantic colors */
+    .dark .prose-invert::-webkit-scrollbar {
+        width: 8px;
+        height: 8px;
+    }
+
+    .dark .prose-invert::-webkit-scrollbar-track {
+        background: rgb(var(--color-base-800));
+        border-radius: 4px;
+    }
+
+    .dark .prose-invert::-webkit-scrollbar-thumb {
+        background: rgb(var(--color-base-700));
+        border-radius: 4px;
+    }
+
+    .dark .prose-invert::-webkit-scrollbar-thumb:hover {
+        background: rgb(var(--color-base-600));
+    }
+</style>
+{% endif %}

django_cfg/modules/django_admin/templates/django_admin/markdown_docs_block.html

@@ -0,0 +1,37 @@
+{% load static %}
+{# Markdown Documentation Block Template #}
+{#
+Usage:
+    {% include "django_admin/markdown_docs_block.html" with
+        content=markdown_content
+        title="Documentation"
+        collapsible=True
+        default_open=False
+    %}
+#}
+
+<div class="mb-6">
+    {% if collapsible %}
+    <details class="group border border-base-200 dark:border-base-700 rounded-lg overflow-hidden bg-white dark:bg-base-800 shadow-sm hover:shadow-md transition-shadow"{% if default_open %} open{% endif %}>
+        <summary class="cursor-pointer px-4 py-3 bg-base-50 dark:bg-base-900 hover:bg-base-100 dark:hover:bg-base-800 transition-colors flex items-center gap-2 select-none">
+            <span class="material-symbols-outlined text-base text-primary-600 dark:text-primary-400 group-open:rotate-90 transition-transform">chevron_right</span>
+            <span class="font-semibold text-sm text-font-default-light dark:text-font-default-dark">{{ title|default:"Documentation" }}</span>
+            <span class="text-xs text-font-subtle-light dark:text-font-subtle-dark ml-auto">{% if default_open %}Click to collapse{% else %}Click to expand{% endif %}</span>
+        </summary>
+        <div class="p-4 bg-white dark:bg-base-800"{% if max_height %} style="max-height: {{ max_height }}; overflow-y: auto;"{% endif %}>
+            {{ content|safe }}
+        </div>
+    </details>
+    {% else %}
+    <div class="border border-base-200 dark:border-base-700 rounded-lg overflow-hidden bg-white dark:bg-base-800 shadow-sm">
+        {% if title %}
+        <div class="px-4 py-3 bg-base-50 dark:bg-base-900 border-b border-base-200 dark:border-base-700">
+            <h3 class="font-semibold text-sm text-font-default-light dark:text-font-default-dark">{{ title }}</h3>
+        </div>
+        {% endif %}
+        <div class="p-4"{% if max_height %} style="max-height: {{ max_height }}; overflow-y: auto;"{% endif %}>
+            {{ content|safe }}
+        </div>
+    </div>
+    {% endif %}
+</div>

django_cfg/modules/django_admin/utils/__init__.py

@@ -11,6 +11,7 @@ from .decorators import (
 )
 from .displays import DateTimeDisplay, MoneyDisplay, UserDisplay
 from .html_builder import HtmlBuilder
+from .markdown_renderer import MarkdownRenderer
 
 __all__ = [
     # Display utilities
@@ -23,6 +24,8 @@ __all__ = [
     "CounterBadge",
     # HTML Builder
     "HtmlBuilder",
+    # Markdown Renderer
+    "MarkdownRenderer",
     # Decorators
     "computed_field",
     "badge_field",

django_cfg/modules/django_admin/utils/html_builder.py

@@ -2,17 +2,19 @@
 Universal HTML builder for Django Admin display methods.
 """
 
+from pathlib import Path
 from typing import Any, List, Optional, Union
 
 from django.utils.html import escape, format_html
 from django.utils.safestring import SafeString
 
 from ..icons import Icons
+from .markdown_renderer import MarkdownRenderer
 
 
 class HtmlBuilder:
     """
-    Universal HTML builder with Material Icons support.
+    Universal HTML builder with Material Icons support and Markdown rendering.
 
     Usage in admin methods:
         def stats(self, obj):
@@ -20,6 +22,9 @@ class HtmlBuilder:
                 self.html.icon_text(Icons.EDIT, obj.posts_count),
                 self.html.icon_text(Icons.CHAT, obj.comments_count),
             ])
+
+        def documentation(self, obj):
+            return self.html.markdown_docs(obj.docs_path)
     """
 
     @staticmethod
@@ -276,3 +281,91 @@ class HtmlBuilder:
             style,
             escape(str(text))
         )
+
+    @staticmethod
+    def markdown(
+        text: str,
+        css_class: str = "",
+        max_height: Optional[str] = None,
+        enable_plugins: bool = True
+    ) -> SafeString:
+        """
+        Render markdown text to beautifully styled HTML.
+
+        Delegates to MarkdownRenderer.render_markdown() for actual rendering.
+
+        Args:
+            text: Markdown content
+            css_class: Additional CSS classes
+            max_height: Max height with scrolling (e.g., "400px", "20rem")
+            enable_plugins: Enable mistune plugins (tables, strikethrough, etc.)
+
+        Usage:
+            # Simple markdown rendering
+            html.markdown("# Hello\\n\\nThis is **bold** text")
+
+            # With custom styling
+            html.markdown(obj.description, css_class="my-custom-class")
+
+            # With max height for long content
+            html.markdown(obj.documentation, max_height="500px")
+
+        Returns:
+            SafeString with rendered HTML
+        """
+        return MarkdownRenderer.render_markdown(
+            text=text,
+            css_class=css_class,
+            max_height=max_height,
+            enable_plugins=enable_plugins
+        )
+
+    @staticmethod
+    def markdown_docs(
+        content: Union[str, Path],
+        collapsible: bool = True,
+        title: str = "Documentation",
+        icon: str = "description",
+        max_height: Optional[str] = "500px",
+        enable_plugins: bool = True,
+        default_open: bool = False
+    ) -> SafeString:
+        """
+        Render markdown documentation from string or file with collapsible UI.
+
+        Auto-detects whether content is a file path or markdown string.
+
+        Args:
+            content: Markdown string or path to .md file
+            collapsible: Wrap in collapsible details/summary
+            title: Title for collapsible section
+            icon: Material icon name for title
+            max_height: Max height for scrolling
+            enable_plugins: Enable markdown plugins
+            default_open: Open by default if collapsible
+
+        Usage:
+            # From string with collapse
+            html.markdown_docs(obj.description, title="Description")
+
+            # From file
+            html.markdown_docs("docs/api.md", title="API Documentation")
+
+            # Simple, no collapse
+            html.markdown_docs(obj.notes, collapsible=False)
+
+            # Open by default
+            html.markdown_docs(obj.readme, default_open=True)
+
+        Returns:
+            Rendered markdown with beautiful Tailwind styling
+        """
+        return MarkdownRenderer.render(
+            content=content,
+            collapsible=collapsible,
+            title=title,
+            icon=icon,
+            max_height=max_height,
+            enable_plugins=enable_plugins,
+            default_open=default_open
+        )