From f8f051f4e907d9908eb7d81c0e24c085a94a7826 Mon Sep 17 00:00:00 2001 From: Egor fureunoir Gorbunov Date: Sat, 21 Feb 2026 19:52:28 +0300 Subject: [PATCH] feat(admin-docs): add base structure and templates for admin documentation Introduce templates for admin documentation, including model details, views, template tags, filters, and bookmarklets. This enhances the admin interface by providing detailed documentation directly within the application. --- .../templates/admin_doc/bookmarklets.html | 34 +++++++ engine/core/templates/admin_doc/index.html | 58 ++++++++++++ .../templates/admin_doc/missing_docutils.html | 25 +++++ .../templates/admin_doc/model_detail.html | 91 +++++++++++++++++++ .../core/templates/admin_doc/model_index.html | 55 +++++++++++ .../templates/admin_doc/template_detail.html | 42 +++++++++ .../admin_doc/template_filter_index.html | 63 +++++++++++++ .../admin_doc/template_tag_index.html | 63 +++++++++++++ .../core/templates/admin_doc/view_detail.html | 43 +++++++++ .../core/templates/admin_doc/view_index.html | 66 ++++++++++++++ .../unfold/helpers/fieldsets_tabs.html | 35 +++++++ 11 files changed, 575 insertions(+) create mode 100644 engine/core/templates/admin_doc/bookmarklets.html create mode 100644 engine/core/templates/admin_doc/index.html create mode 100644 engine/core/templates/admin_doc/missing_docutils.html create mode 100644 engine/core/templates/admin_doc/model_detail.html create mode 100644 engine/core/templates/admin_doc/model_index.html create mode 100644 engine/core/templates/admin_doc/template_detail.html create mode 100644 engine/core/templates/admin_doc/template_filter_index.html create mode 100644 engine/core/templates/admin_doc/template_tag_index.html create mode 100644 engine/core/templates/admin_doc/view_detail.html create mode 100644 engine/core/templates/admin_doc/view_index.html create mode 100644 engine/core/templates/unfold/helpers/fieldsets_tabs.html diff --git a/engine/core/templates/admin_doc/bookmarklets.html b/engine/core/templates/admin_doc/bookmarklets.html new file mode 100644 index 00000000..33d3822c --- /dev/null +++ b/engine/core/templates/admin_doc/bookmarklets.html @@ -0,0 +1,34 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate "Documentation bookmarklets" %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Bookmarklets' %} +
+{% endblock %} + +{% block content %} +

{% translate "Documentation bookmarklets" %}

+ +

{% blocktranslate trimmed %} + To install bookmarklets, drag the link to your bookmarks toolbar, or right-click + the link and add it to your bookmarks. Now you can select the bookmarklet + from any page in the site. + {% endblocktranslate %}

+ +
+
+
+ bookmark + {% translate "Documentation for this page" %} +
+

{% translate "Jumps you from any page to the documentation for the view that generates that page." %}

+
+
+{% endblock %} diff --git a/engine/core/templates/admin_doc/index.html b/engine/core/templates/admin_doc/index.html new file mode 100644 index 00000000..aa6c06f6 --- /dev/null +++ b/engine/core/templates/admin_doc/index.html @@ -0,0 +1,58 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Documentation' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} +
+{% endblock %} + +{% block content %} +

{% translate 'Documentation' %}

+ +
+ +
+ database +

{% translate 'Models' %}

+
+

{% translate 'Models are descriptions of all the objects in the system and their associated fields. Each model has a list of fields which can be accessed as template variables' %}.

+ + + +
+ visibility +

{% translate 'Views' %}

+
+

{% translate 'Each page on the public site is generated by a view. The view defines which template is used to generate the page and which objects are available to that template.' %}

+ + + +
+ code +

{% translate 'Tags' %}

+
+

{% translate 'List of all the template tags and their functions.' %}

+ + + +
+ filter_alt +

{% translate 'Filters' %}

+
+

{% translate 'Filters are actions which can be applied to variables in a template to alter the output.' %}

+ + + +
+ bookmark +

{% translate 'Bookmarklets' %}

+
+

{% translate 'Tools for your browser to quickly access admin functionality.' %}

+ +
+{% endblock %} diff --git a/engine/core/templates/admin_doc/missing_docutils.html b/engine/core/templates/admin_doc/missing_docutils.html new file mode 100644 index 00000000..d977142c --- /dev/null +++ b/engine/core/templates/admin_doc/missing_docutils.html @@ -0,0 +1,25 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Please install docutils' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} +
+{% endblock %} + +{% block content %} +
+
+ warning +
+

{% translate 'Documentation' %}

+

{% blocktranslate with "https://docutils.sourceforge.io/" as link %}The admin documentation system requires Python's docutils library.{% endblocktranslate %}

+

{% blocktranslate with "https://pypi.org/project/docutils/" as link %}Please ask your administrators to install docutils.{% endblocktranslate %}

+
+
+
+{% endblock %} diff --git a/engine/core/templates/admin_doc/model_detail.html b/engine/core/templates/admin_doc/model_detail.html new file mode 100644 index 00000000..47830833 --- /dev/null +++ b/engine/core/templates/admin_doc/model_detail.html @@ -0,0 +1,91 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% blocktranslate %}Model: {{ name }}{% endblocktranslate %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Models' %} + chevron_right + {{ name }} +
+{% endblock %} + +{% block content %} +
+

{{ name }}

+ {% if summary %}

{{ summary }}

{% endif %} + {% if description %}
{{ description }}
{% endif %} +
+ +
+
+

+ list + {% translate 'Fields' %} +

+
+
+ + + + + + + + + + {% for field in fields|dictsort:"name" %} + + + + + + {% endfor %} + +
{% translate 'Field' %}{% translate 'Type' %}{% translate 'Description' %}
{{ field.name }} + {{ field.data_type }} + {{ field.verbose }}{% if field.help_text %} — {{ field.help_text|safe }}{% endif %}
+
+
+ + {% if methods %} +
+
+

+ function + {% translate 'Methods with arguments' %} +

+
+
+ + + + + + + + + + {% for method in methods|dictsort:"name" %} + + + + + + {% endfor %} + +
{% translate 'Method' %}{% translate 'Arguments' %}{% translate 'Description' %}
{{ method.name }}{{ method.arguments }}{{ method.verbose }}
+
+
+ {% endif %} + + + arrow_back + {% translate 'Back to Model documentation' %} + +{% endblock %} diff --git a/engine/core/templates/admin_doc/model_index.html b/engine/core/templates/admin_doc/model_index.html new file mode 100644 index 00000000..ece20469 --- /dev/null +++ b/engine/core/templates/admin_doc/model_index.html @@ -0,0 +1,55 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Models' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Models' %} +
+{% endblock %} + +{% block content %} +

{% translate 'Model documentation' %}

+ + {% regroup models by app_config as grouped_models %} + +
+
+ {% for group in grouped_models %} +
+
+

{{ group.grouper.verbose_name }}

+ {{ group.grouper.name }} +
+
+ {% for model in group.list %} + + table_chart + {{ model.object_name }} + + {% endfor %} +
+
+ {% endfor %} +
+ +
+
+
+

{% translate 'Model groups' %}

+
+ +
+
+
+{% endblock %} diff --git a/engine/core/templates/admin_doc/template_detail.html b/engine/core/templates/admin_doc/template_detail.html new file mode 100644 index 00000000..28eb7740 --- /dev/null +++ b/engine/core/templates/admin_doc/template_detail.html @@ -0,0 +1,42 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% blocktranslate %}Template: {{ name }}{% endblocktranslate %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Templates' %} +
+{% endblock %} + +{% block content %} +

{% blocktranslate %}Template: {{ name }}{% endblocktranslate %}

+ +
+
+

{% blocktranslate %}Search path for template {{ name }}:{% endblocktranslate %}

+
+
+ {% for template in templates|dictsort:"order" %} +
+ {{ template.order }} + {{ template.file }} + {% if not template.exists %} + {% translate '(does not exist)' %} + {% else %} + check_circle + {% endif %} +
+ {% endfor %} +
+
+ + + arrow_back + {% translate 'Back to Documentation' %} + +{% endblock %} diff --git a/engine/core/templates/admin_doc/template_filter_index.html b/engine/core/templates/admin_doc/template_filter_index.html new file mode 100644 index 00000000..f67f7f42 --- /dev/null +++ b/engine/core/templates/admin_doc/template_filter_index.html @@ -0,0 +1,63 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Template filters' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Filters' %} +
+{% endblock %} + +{% block content %} +

{% translate 'Template filter documentation' %}

+ + {% regroup filters|dictsort:"library" by library as filter_libraries %} + +
+
+ {% for library in filter_libraries %} +
+
+

{% firstof library.grouper _("Built-in filters") %}

+ {% if library.grouper %} +

+ {% blocktranslate with code="{"|add:"% load "|add:library.grouper|add:" %"|add:"}" %}To use these filters, put {{ code }} in your template before using the filter.{% endblocktranslate %} +

+ {% endif %} +
+
+ {% for filter in library.list|dictsort:"name" %} +
+

{{ filter.name }}

+
+ {{ filter.title }} + {{ filter.body }} +
+
+ {% endfor %} +
+
+ {% endfor %} +
+ +
+ {% for library in filter_libraries %} +
+
+

{% firstof library.grouper _("Built-in filters") %}

+
+ +
+ {% endfor %} +
+
+{% endblock %} diff --git a/engine/core/templates/admin_doc/template_tag_index.html b/engine/core/templates/admin_doc/template_tag_index.html new file mode 100644 index 00000000..0342efeb --- /dev/null +++ b/engine/core/templates/admin_doc/template_tag_index.html @@ -0,0 +1,63 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Template tags' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Tags' %} +
+{% endblock %} + +{% block content %} +

{% translate 'Template tag documentation' %}

+ + {% regroup tags|dictsort:"library" by library as tag_libraries %} + +
+
+ {% for library in tag_libraries %} +
+
+

{% firstof library.grouper _("Built-in tags") %}

+ {% if library.grouper %} +

+ {% blocktranslate with code="{"|add:"% load "|add:library.grouper|add:" %"|add:"}" %}To use these tags, put {{ code }} in your template before using the tag.{% endblocktranslate %} +

+ {% endif %} +
+
+ {% for tag in library.list|dictsort:"name" %} +
+

{{ tag.name }}

+
+

{{ tag.title|striptags }}

+ {{ tag.body }} +
+
+ {% endfor %} +
+
+ {% endfor %} +
+ +
+ {% for library in tag_libraries %} +
+
+

{% firstof library.grouper _("Built-in tags") %}

+
+ +
+ {% endfor %} +
+
+{% endblock %} diff --git a/engine/core/templates/admin_doc/view_detail.html b/engine/core/templates/admin_doc/view_detail.html new file mode 100644 index 00000000..1758959d --- /dev/null +++ b/engine/core/templates/admin_doc/view_detail.html @@ -0,0 +1,43 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% blocktranslate %}View: {{ name }}{% endblocktranslate %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Views' %} + chevron_right + {{ name }} +
+{% endblock %} + +{% block content %} +
+
+

{{ name }}

+ {% if summary %}

{{ summary }}

{% endif %} +
+
+ {{ body }} + + {% if meta.Context %} +

{% translate 'Context:' %}

+

{{ meta.Context }}

+ {% endif %} + + {% if meta.Templates %} +

{% translate 'Templates:' %}

+

{{ meta.Templates }}

+ {% endif %} +
+
+ + + arrow_back + {% translate 'Back to View documentation' %} + +{% endblock %} diff --git a/engine/core/templates/admin_doc/view_index.html b/engine/core/templates/admin_doc/view_index.html new file mode 100644 index 00000000..22b3408b --- /dev/null +++ b/engine/core/templates/admin_doc/view_index.html @@ -0,0 +1,66 @@ +{% extends "admin/base_site.html" %} +{% load i18n %} + +{% block title %}{% translate 'Views' %}{% endblock %} + +{% block breadcrumbs %} +
+ {% translate 'Home' %} + chevron_right + {% translate 'Documentation' %} + chevron_right + {% translate 'Views' %} +
+{% endblock %} + +{% block content %} +

{% translate 'View documentation' %}

+ + {% regroup views|dictsort:'namespace' by namespace as views_by_ns %} + +
+
+ {% for ns_views in views_by_ns %} +
+
+

+ {% if ns_views.grouper %} + {% blocktranslate with ns_views.grouper as name %}Views by namespace {{ name }}{% endblocktranslate %} + {% else %} + {% blocktranslate %}Views by empty namespace{% endblocktranslate %} + {% endif %} +

+
+
+ {% for view in ns_views.list|dictsort:"url" %} + {% ifchanged %} +
+ {{ view.url }} +

+ {% blocktranslate with view.full_name as full_name and view.url_name as url_name %}View function: {{ full_name }}. Name: {{ url_name }}.{% endblocktranslate %} +

+ {% if view.title %}

{{ view.title }}

{% endif %} +
+ {% endifchanged %} + {% endfor %} +
+
+ {% endfor %} +
+ +
+
+
+

{% translate 'Jump to namespace' %}

+
+ +
+
+
+{% endblock %} diff --git a/engine/core/templates/unfold/helpers/fieldsets_tabs.html b/engine/core/templates/unfold/helpers/fieldsets_tabs.html new file mode 100644 index 00000000..668bc031 --- /dev/null +++ b/engine/core/templates/unfold/helpers/fieldsets_tabs.html @@ -0,0 +1,35 @@ +{% load unfold %} +{% load filters %} + +{% with tabs=adminform|tabs %} + {% if tabs %} + {% with active_tab=tabs|tabs_active_unicode %} +
+
+ +
+ + {% for fieldset in tabs %} +
+ {% include 'admin/includes/fieldset.html' with stacked=1 %} +
+ {% endfor %} +
+ {% endwith %} + {% endif %} +{% endwith %}