django-admin-wiki 0.1.0__py3-none-any.whl

django_admin_wiki/__init__.py

@@ -0,0 +1,3 @@
+"""django-admin-wiki — collaborative staff wiki for Django Admin."""
+
+__version__ = "0.1.0"

django_admin_wiki/admin.py

@@ -0,0 +1,89 @@
+from django.contrib import admin
+from django.urls import reverse
+from django.utils.html import format_html
+
+from django_admin_wiki.forms import get_editor_widget
+from django_admin_wiki.models import WikiPage, WikiRevision
+from django_admin_wiki.render import sanitize_wiki_html
+from django_admin_wiki.repositories import is_cloud_storage
+from django_admin_wiki.services import save_wiki_page
+
+
+class WikiRevisionInline(admin.TabularInline):
+    model = WikiRevision
+    extra = 0
+    can_delete = False
+    readonly_fields = ("title", "author", "created_at", "content_preview")
+    fields = ("created_at", "author", "title", "content_preview")
+
+    def content_preview(self, obj):
+        text = obj.content or ""
+        return text[:200] + ("…" if len(text) > 200 else "")
+
+    content_preview.short_description = "Preview"
+
+
+class WikiPageAdmin(admin.ModelAdmin):
+    change_list_template = "admin/django_admin_wiki/wikipage/change_list.html"
+    list_display = (
+        "title",
+        "slug",
+        "parent",
+        "sort_order",
+        "updated_at",
+        "updated_by",
+        "open_wiki",
+    )
+    list_filter = ("parent",)
+    search_fields = ("title", "slug", "nav_label", "content")
+    prepopulated_fields = {"slug": ("title",)}
+    readonly_fields = ("created_at", "updated_at", "author", "updated_by")
+    inlines = [WikiRevisionInline]
+    fieldsets = (
+        (
+            None,
+            {
+                "fields": (
+                    "title",
+                    "slug",
+                    "nav_label",
+                    "parent",
+                    "sort_order",
+                    "content",
+                ),
+            },
+        ),
+        (
+            "Metadata",
+            {
+                "fields": ("author", "updated_by", "created_at", "updated_at"),
+            },
+        ),
+    )
+
+    def formfield_for_dbfield(self, db_field, request, **kwargs):
+        formfield = super().formfield_for_dbfield(db_field, request, **kwargs)
+        if db_field.name == "content" and formfield is not None:
+            formfield.widget = get_editor_widget()
+        return formfield
+
+    def open_wiki(self, obj):
+        url = reverse("django_admin_wiki:wiki_page", args=[obj.slug])
+        return format_html('<a href="{}" target="_blank">Open</a>', url)
+
+    open_wiki.short_description = "Wiki"
+
+    def save_model(self, request, obj, form, change):
+        obj.content = sanitize_wiki_html(obj.content or "")
+        save_wiki_page(obj, user=request.user, create_revision=True)
+
+
+def _register_admin():
+    # In cloud mode, local WikiPage tables are not used — skip ModelAdmin registration.
+    if is_cloud_storage():
+        return
+    if not admin.site.is_registered(WikiPage):
+        admin.site.register(WikiPage, WikiPageAdmin)
+
+
+_register_admin()

django_admin_wiki/apps.py

@@ -0,0 +1,57 @@
+from django.apps import AppConfig
+from django.core.checks import Warning, register
+from django.db.models.signals import post_migrate
+
+
+def _ensure_wiki_groups(sender, **kwargs):
+    if sender.name != "django_admin_wiki":
+        return
+    from django_admin_wiki.permissions import ensure_wiki_groups
+
+    ensure_wiki_groups()
+
+
+class DjangoAdminWikiConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_wiki"
+    label = "django_admin_wiki"
+    verbose_name = "Admin Wiki"
+
+    def ready(self):
+        post_migrate.connect(_ensure_wiki_groups, sender=self)
+
+
+@register()
+def check_cloud_storage_settings(app_configs, **kwargs):
+    from django.conf import settings
+
+    from django_admin_wiki.conf import wiki_settings
+
+    errors = []
+    storage = (wiki_settings.STORAGE or "local").lower()
+    if storage == "cloud":
+        if not wiki_settings.CLOUD_API_URL or not wiki_settings.CLOUD_API_KEY:
+            errors.append(
+                Warning(
+                    'STORAGE="cloud" requires CLOUD_API_URL and CLOUD_API_KEY.',
+                    id="django_admin_wiki.W001",
+                )
+            )
+        if not wiki_settings.CLOUD_API_KEY_READ:
+            errors.append(
+                Warning(
+                    'STORAGE="cloud": set CLOUD_API_KEY_READ so read-only Django users '
+                    "can load pages (create a read-only key in the Premium dashboard).",
+                    id="django_admin_wiki.W003",
+                )
+            )
+        migration_modules = getattr(settings, "MIGRATION_MODULES", {}) or {}
+        if migration_modules.get("django_admin_wiki") is not None:
+            errors.append(
+                Warning(
+                    'For Premium cloud mode set MIGRATION_MODULES = {"django_admin_wiki": None} '
+                    "so host migrate does not create local wiki tables.",
+                    id="django_admin_wiki.W002",
+                )
+            )
+    return errors

django_admin_wiki/conf.py

@@ -0,0 +1,94 @@
+"""Configurable settings for django-admin-wiki.
+
+Read from Django settings dict ``DJANGO_ADMIN_WIKI``::
+
+    DJANGO_ADMIN_WIKI = {
+        "SEARCH_BACKEND": "postgres",  # or "fallback"
+        "SEARCH_CONFIG": "french",
+        "EDITOR": "summernote",  # "summernote" | "textarea" | "custom"
+        "EDITOR_WIDGET": None,  # dotted path when EDITOR="custom"
+        "ALLOW_MARKDOWN_READ": True,
+        "BLEACH_ALLOWED_TAGS": None,
+        "BLEACH_ALLOWED_ATTRIBUTES": None,
+        "DOCS_DIR": None,
+        "MKDOCS_YML": None,
+        "MEDIA_ROOT_SUBDIR": "wiki",
+        "MEDIA_BACKEND": "local",  # "local" | "django" (default_storage / S3)
+        "MEDIA_MAX_UPLOAD_BYTES": 5 * 1024 * 1024,
+        "MEDIA_ALLOWED_CONTENT_TYPES": None,  # None → image/* defaults
+        "HOME_SLUG": "index",
+        "URL_PREFIX": "wiki/",
+        "MAX_NAV_DEPTH": 3,  # root + up to 2 nested levels
+        "STORAGE": "local",  # or "cloud" for Premium (no local wiki tables)
+        "CLOUD_API_URL": "https://django-admin-wiki.enprod.fr",
+        "CLOUD_API_KEY": "daw_live_...",  # write key
+        "CLOUD_API_KEY_READ": "daw_live_...",  # read-only key (readers)
+    }
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from django.conf import settings
+
+DEFAULTS = {
+    "SEARCH_BACKEND": "postgres",
+    "SEARCH_CONFIG": "french",
+    "EDITOR": "summernote",
+    "EDITOR_WIDGET": None,
+    "ALLOW_MARKDOWN_READ": True,
+    "BLEACH_ALLOWED_TAGS": None,
+    "BLEACH_ALLOWED_ATTRIBUTES": None,
+    "DOCS_DIR": None,
+    "MKDOCS_YML": None,
+    "MEDIA_ROOT_SUBDIR": "wiki",
+    "MEDIA_BACKEND": "local",  # "local" | "django" (use Django STORAGES / Cellar)
+    "MEDIA_MAX_UPLOAD_BYTES": 5 * 1024 * 1024,
+    "MEDIA_ALLOWED_CONTENT_TYPES": None,
+    "HOME_SLUG": "index",
+    "URL_PREFIX": "wiki/",
+    "MAX_NAV_DEPTH": 3,
+    "STORAGE": "local",  # "local" | "cloud"
+    "CLOUD_API_URL": "",
+    "CLOUD_API_KEY": "",
+    "CLOUD_API_KEY_READ": "",
+}
+
+
+class WikiSettings:
+    """Lazy accessor for ``DJANGO_ADMIN_WIKI`` with defaults."""
+
+    def __getattr__(self, name: str):
+        if name not in DEFAULTS:
+            raise AttributeError(f"Unknown wiki setting: {name}")
+        user = getattr(settings, "DJANGO_ADMIN_WIKI", None) or {}
+        return user.get(name, DEFAULTS[name])
+
+    def get_docs_dir(self) -> Path:
+        configured = self.DOCS_DIR
+        if configured:
+            return Path(configured)
+        return Path(settings.BASE_DIR) / "wiki_docs"
+
+    def get_mkdocs_yml(self) -> Path:
+        configured = self.MKDOCS_YML
+        if configured:
+            return Path(configured)
+        return self.get_docs_dir() / "mkdocs.yml"
+
+    def get_media_root(self) -> Path:
+        """Directory served under /wiki/media/ (defaults to docs dir)."""
+        return self.get_docs_dir()
+
+    def url_prefix_path(self) -> str:
+        """URL prefix without leading slash, with trailing slash (e.g. ``wiki/``)."""
+        prefix = (self.URL_PREFIX or "wiki/").strip("/")
+        return f"{prefix}/" if prefix else ""
+
+    def wiki_url_root(self) -> str:
+        """Absolute-ish path root for link rewriting (e.g. ``/wiki/``)."""
+        return f"/{self.url_prefix_path()}"
+
+
+wiki_settings = WikiSettings()

django_admin_wiki/fields.py

@@ -0,0 +1,29 @@
+"""Search-vector field that works on PostgreSQL and other backends."""
+
+from django.db import models
+
+
+class WikiSearchVectorField(models.Field):
+    """Maps to ``tsvector`` on PostgreSQL; unused ``text`` elsewhere (fallback search)."""
+
+    description = "PostgreSQL tsvector (text stub on other backends)"
+    empty_strings_allowed = True
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("null", True)
+        kwargs.setdefault("editable", False)
+        super().__init__(*args, **kwargs)
+
+    def db_type(self, connection):
+        if connection.vendor == "postgresql":
+            return "tsvector"
+        return "text"
+
+    def from_db_value(self, value, expression, connection):
+        return value
+
+    def to_python(self, value):
+        return value
+
+    def get_prep_value(self, value):
+        return value

django_admin_wiki/forms.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+from django import forms
+from django.urls import NoReverseMatch, reverse
+
+from django_admin_wiki.conf import wiki_settings
+from django_admin_wiki.render import content_for_editor, sanitize_wiki_html
+from django_admin_wiki.repositories.base import PageRecord
+
+
+def get_editor_widget():
+    """Return the content widget based on ``DJANGO_ADMIN_WIKI['EDITOR']``.
+
+    Defaults to Summernote (WYSIWYG). Set ``EDITOR`` to ``"textarea"`` or
+    ``"custom"`` (with ``EDITOR_WIDGET``) to override.
+    """
+    editor = (wiki_settings.EDITOR or "summernote").lower()
+    if editor == "textarea":
+        return forms.Textarea(attrs={"rows": 18, "class": "wiki-md-editor"})
+    if editor == "custom":
+        path = wiki_settings.EDITOR_WIDGET
+        if not path:
+            raise ValueError(
+                'DJANGO_ADMIN_WIKI["EDITOR_WIDGET"] is required when EDITOR="custom"'
+            )
+        module_path, attr = path.rsplit(".", 1)
+        obj = getattr(import_module(module_path), attr)
+        return obj() if isinstance(obj, type) else obj
+    try:
+        from django_admin_wiki.widgets import WikiSummernoteWidget
+    except ImportError as exc:
+        raise ImportError(
+            'EDITOR="summernote" requires django-summernote. '
+            'Install it or set DJANGO_ADMIN_WIKI["EDITOR"] = "textarea".'
+        ) from exc
+    upload_url = ""
+    try:
+        upload_url = reverse("django_admin_wiki:wiki_media_upload")
+    except NoReverseMatch:
+        pass
+    return WikiSummernoteWidget(upload_url=upload_url)
+
+
+class WikiPageEditForm(forms.Form):
+    title = forms.CharField(label="Title", max_length=255)
+    slug = forms.SlugField(label="Slug", max_length=255, required=False)
+    nav_label = forms.CharField(label="Menu label", max_length=255, required=False)
+    parent = forms.ChoiceField(label="Parent", required=False)
+    sort_order = forms.IntegerField(label="Sort order", initial=0, required=False)
+    content = forms.CharField(label="Content", required=False)
+
+    def __init__(self, *args, parents=None, page: PageRecord | None = None, **kwargs):
+        # Back-compat: parents_qs (ORM) or parents (PageRecord list)
+        parents_qs = kwargs.pop("parents_qs", None)
+        super().__init__(*args, **kwargs)
+        self.fields["content"].widget = get_editor_widget()
+
+        choices = [("", "— Root —")]
+        if parents is not None:
+            for p in parents:
+                choices.append((p.slug, p.display_label()))
+        elif parents_qs is not None:
+            for p in parents_qs:
+                choices.append((p.slug, getattr(p, "display_label", lambda: p.title)()))
+        self.fields["parent"].choices = choices
+
+        if page is not None:
+            self.fields["slug"].widget = forms.HiddenInput()
+            self.fields["title"].initial = page.title
+            self.fields["nav_label"].initial = page.nav_label
+            self.fields["parent"].initial = page.parent_slug or ""
+            self.fields["sort_order"].initial = page.sort_order
+            self.fields["content"].initial = content_for_editor(page.content)
+        else:
+            self.fields["slug"].help_text = "Optional — generated from the title if empty"
+
+    def clean_content(self):
+        return sanitize_wiki_html(self.cleaned_data.get("content") or "")
+
+    def clean_parent(self):
+        value = self.cleaned_data.get("parent") or ""
+        return value or None

django_admin_wiki/management/commands/import_mkdocs.py

@@ -0,0 +1,234 @@
+import re
+from pathlib import Path
+
+import yaml
+from django.core.management.base import BaseCommand
+from django.utils.text import slugify
+
+from django_admin_wiki.conf import wiki_settings
+from django_admin_wiki.models import WikiPage
+from django_admin_wiki.render import markdown_to_html, sanitize_wiki_html
+from django_admin_wiki.services import refresh_search_vector
+
+
+class Command(BaseCommand):
+    help = (
+        "Import MkDocs Markdown files into WikiPage. "
+        "By default converts Markdown to HTML for the WYSIWYG editor."
+    )
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--docs-dir",
+            type=str,
+            default="",
+            help="Docs directory (default: DJANGO_ADMIN_WIKI.DOCS_DIR or wiki_docs/)",
+        )
+        parser.add_argument(
+            "--mkdocs",
+            type=str,
+            default="",
+            help="Path to mkdocs.yml (default: DOCS_DIR/mkdocs.yml)",
+        )
+        parser.add_argument(
+            "--slugs",
+            type=str,
+            default="",
+            help="Comma-separated slugs to import (empty = all pages).",
+        )
+        parser.add_argument(
+            "--keep-markdown",
+            action="store_true",
+            help="Do not convert to HTML (keep raw Markdown).",
+        )
+
+    def handle(self, *args, **opts):
+        docs_dir = Path(opts["docs_dir"] or wiki_settings.get_docs_dir())
+        mkdocs_path = Path(opts["mkdocs"] or wiki_settings.get_mkdocs_yml())
+        keep_markdown = bool(opts["keep_markdown"])
+        only_slugs = {
+            slugify(s.strip()) for s in (opts["slugs"] or "").split(",") if s.strip()
+        }
+
+        nav_meta = {}
+        if mkdocs_path.exists():
+            data = self._load_mkdocs_yaml(mkdocs_path)
+            nav_meta = self._flatten_nav(data.get("nav") or [])
+
+        md_files = sorted(docs_dir.rglob("*.md"))
+        if not md_files:
+            self.stderr.write(f"No .md files in {docs_dir}")
+            return
+
+        created_count = 0
+        updated_count = 0
+        skipped_count = 0
+        pages_by_file = {}
+
+        for md_file in md_files:
+            rel = md_file.relative_to(docs_dir).with_suffix("")
+            file_key = str(rel).replace("\\", "/")
+            slug = slugify("-".join(rel.parts)) or slugify(md_file.stem)
+            if only_slugs and slug not in only_slugs:
+                skipped_count += 1
+                continue
+            raw = md_file.read_text(encoding="utf-8")
+            title = self._extract_title(raw, md_file.stem)
+            content = self._rewrite_content(raw)
+            if not keep_markdown:
+                content = sanitize_wiki_html(markdown_to_html(content))
+            meta = nav_meta.get(file_key) or nav_meta.get(md_file.name) or {}
+            nav_label = meta.get("label") or ""
+            sort_order = meta.get("sort_order", 0)
+
+            page, created = WikiPage.objects.update_or_create(
+                slug=slug,
+                defaults={
+                    "title": title,
+                    "content": content,
+                    "nav_label": nav_label,
+                    "sort_order": sort_order,
+                },
+            )
+            pages_by_file[file_key] = page
+            pages_by_file[md_file.name] = page
+            refresh_search_vector(page)
+            if created:
+                created_count += 1
+                self.stdout.write(f"Created  {slug}")
+            else:
+                updated_count += 1
+                self.stdout.write(f"Updated  {slug}")
+
+        for file_key, meta in nav_meta.items():
+            page = pages_by_file.get(file_key)
+            if not page:
+                continue
+            parent_file = meta.get("parent_file")
+            if parent_file and parent_file in pages_by_file:
+                parent = pages_by_file[parent_file]
+                if parent.pk != page.pk:
+                    page.parent = parent
+                    page.save(update_fields=["parent"])
+            elif meta.get("is_section_root"):
+                page.parent = None
+                page.save(update_fields=["parent"])
+
+        fmt = "Markdown" if keep_markdown else "HTML (WYSIWYG)"
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Done ({fmt}): {created_count} created, {updated_count} updated"
+                + (f", {skipped_count} skipped (--slugs)" if skipped_count else "")
+            )
+        )
+
+    def _load_mkdocs_yaml(self, mkdocs_path: Path) -> dict:
+        text = mkdocs_path.read_text(encoding="utf-8")
+        text = re.sub(
+            r"^!!python/name:[^\n]+$",
+            "null",
+            text,
+            flags=re.MULTILINE,
+        )
+
+        class SilentLoader(yaml.SafeLoader):
+            pass
+
+        SilentLoader.add_multi_constructor(
+            "tag:yaml.org,2002:python/",
+            lambda loader, suffix, node: None,
+        )
+        return yaml.load(text, Loader=SilentLoader) or {}
+
+    def _extract_title(self, raw: str, stem: str) -> str:
+        for line in raw.splitlines():
+            if line.startswith("# "):
+                return line[2:].strip()
+        return stem.replace("-", " ").replace("_", " ").title()
+
+    def _rewrite_content(self, raw: str) -> str:
+        root = wiki_settings.wiki_url_root()  # e.g. /wiki/
+        media_root = f"{root}media/"
+
+        content = re.sub(
+            r"\]\(([^)/][^)]*?)\.md(#[^)]*)?\)",
+            lambda m: f"]({root}{slugify(Path(m.group(1)).stem)}/{m.group(2) or ''})",
+            raw,
+        )
+        content = re.sub(
+            rf"\]\((?!https?://|{re.escape(root)}|/static/)([^)]+\.(?:png|jpg|jpeg|gif|svg|webp))\)",
+            rf"]({media_root}\1)",
+            content,
+        )
+        return content
+
+    def _flatten_nav(self, nav, parent_file=None, counter=None):
+        if counter is None:
+            counter = [0]
+        result = {}
+        for item in nav:
+            if isinstance(item, str):
+                file_key = item[:-3] if item.endswith(".md") else item
+                counter[0] += 1
+                result[file_key] = {
+                    "label": Path(file_key).name.replace("-", " ").replace("_", " ").title(),
+                    "sort_order": counter[0],
+                    "parent_file": parent_file,
+                }
+                result[Path(item).name if item.endswith(".md") else f"{file_key}.md"] = result[
+                    file_key
+                ]
+            elif isinstance(item, dict):
+                for label, value in item.items():
+                    if isinstance(value, str) and value.endswith(".md"):
+                        file_key = value[:-3]
+                        counter[0] += 1
+                        meta = {
+                            "label": label.strip(),
+                            "sort_order": counter[0],
+                            "parent_file": parent_file,
+                        }
+                        result[file_key] = meta
+                        result[Path(value).name] = meta
+                    elif isinstance(value, list):
+                        first_md = self._first_md(value)
+                        section_parent = None
+                        if first_md:
+                            file_key = first_md[:-3]
+                            counter[0] += 1
+                            meta = {
+                                "label": label.strip(),
+                                "sort_order": counter[0],
+                                "parent_file": None,
+                                "is_section_root": True,
+                            }
+                            result[file_key] = meta
+                            result[Path(first_md).name] = meta
+                            section_parent = file_key
+                            child_nav = (
+                                value[1:] if self._entry_file(value[0]) == first_md else value
+                            )
+                        else:
+                            child_nav = value
+                        result.update(
+                            self._flatten_nav(
+                                child_nav, parent_file=section_parent, counter=counter
+                            )
+                        )
+        return result
+
+    def _first_md(self, items):
+        for item in items:
+            f = self._entry_file(item)
+            if f:
+                return f
+        return None
+
+    def _entry_file(self, item):
+        if isinstance(item, str) and item.endswith(".md"):
+            return item
+        if isinstance(item, dict):
+            for value in item.values():
+                if isinstance(value, str) and value.endswith(".md"):
+                    return value
+        return None

django_admin_wiki/management/commands/refresh_wiki_search_vectors.py

@@ -0,0 +1,15 @@
+from django.core.management.base import BaseCommand
+
+from django_admin_wiki.models import WikiPage
+from django_admin_wiki.services import refresh_search_vector
+
+
+class Command(BaseCommand):
+    help = "Rebuild PostgreSQL search vectors for all wiki pages."
+
+    def handle(self, *args, **options):
+        count = 0
+        for page in WikiPage.objects.iterator():
+            refresh_search_vector(page)
+            count += 1
+        self.stdout.write(self.style.SUCCESS(f"Refreshed search vectors for {count} page(s)."))

django_admin_wiki/management/commands/setup_wiki_groups.py

@@ -0,0 +1,21 @@
+"""Create the standard Wiki readers / Wiki editors groups."""
+
+from django.core.management.base import BaseCommand
+
+from django_admin_wiki.permissions import GROUP_EDITORS, GROUP_READERS, ensure_wiki_groups
+
+
+class Command(BaseCommand):
+    help = (
+        "Create or refresh Django groups "
+        f"'{GROUP_READERS}' (view) and '{GROUP_EDITORS}' (view+add+change)."
+    )
+
+    def handle(self, *args, **options):
+        readers, editors = ensure_wiki_groups()
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"OK — groups ready: '{readers.name}', '{editors.name}'. "
+                "Assign users in Django Admin → Users / Groups."
+            )
+        )