django-app-help 0.1.0__py3-none-any.whl

app_help/__init__.py

@@ -0,0 +1,7 @@
+"""Filesystem-backed Markdown help engine."""
+
+from app_help.engine import HelpEngine
+
+__version__ = "0.1.0"
+
+__all__ = ["HelpEngine"]

app_help/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class DjangoAppHelpConfig(AppConfig):
+    name = 'app_help'

app_help/conf.py

@@ -0,0 +1,31 @@
+"""Recommended Django settings for django-app-help integrations."""
+
+import bleach
+
+#: Bleach tag whitelist for Markdown help content rendered via django-markdownify.
+_MARKDOWN_HELP_TAGS = {
+    *bleach.sanitizer.ALLOWED_TAGS,
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "hr",
+    "p",
+    "pre",
+}
+
+#: Recommended ``MARKDOWNIFY`` settings for help pages rendered with Wildewidgets.
+MARKDOWNIFY = {
+    "default": {
+        "WHITELIST_TAGS": sorted(_MARKDOWN_HELP_TAGS),
+        "MARKDOWN_EXTENSIONS": [
+            "markdown.extensions.fenced_code",
+        ],
+        "LINKIFY_TEXT": {
+            "PARSE_URLS": True,
+            "SKIP_TAGS": ["pre", "code"],
+        },
+    },
+}

app_help/engine.py

@@ -0,0 +1,180 @@
+"""Public Markdown rendering engine for filesystem-backed help content."""
+
+from pathlib import Path, PurePosixPath
+
+from app_help.exceptions import HelpBookNotFoundError, HelpPageNotFoundError, PageNotInBookError
+from app_help.models import Book, Page
+from app_help.parsing import expand_includes, parse_book, parse_front_matter, validate_asset_links, validate_help_links
+
+
+class HelpEngine:
+    """Load help books and render canonical Markdown pages from disk.
+
+    Args:
+        root_path: Help root containing ``books``, ``pages``, ``snippets``, and ``assets`` directories.
+        max_include_depth: Maximum nested snippet include depth.
+    """
+
+    def __init__(self, root_path: str | Path, max_include_depth: int = 5) -> None:
+        #: Help root containing content directories.
+        self.root_path = Path(root_path)
+        #: Maximum nested snippet include depth.
+        self.max_include_depth = max_include_depth
+        #: Directory containing book YAML files.
+        self.books_path = self.root_path / "books"
+        #: Directory containing canonical Markdown pages.
+        self.pages_path = self.root_path / "pages"
+        #: Directory containing help assets.
+        self.assets_path = self.root_path / "assets"
+
+    def render_page(self, page_id: str, book_slug: str | None = None) -> str:
+        """Return expanded Markdown for a page.
+
+        Args:
+            page_id: Logical page ID, such as ``billing/overview``.
+            book_slug: Optional book slug requiring the page to be listed in that book.
+
+        Raises:
+            HelpBookNotFoundError: If ``book_slug`` is provided and missing.
+            HelpPageNotFoundError: If the page file is missing.
+            PageNotInBookError: If the book does not reference the page.
+
+        Returns:
+            Markdown with front matter removed and snippets expanded.
+        """
+        if book_slug is not None:
+            book = self.load_book(book_slug)
+            if not book.contains_page(page_id):
+                raise PageNotInBookError(f"{page_id} is not listed in book {book_slug}")
+
+        page = self.load_page(page_id)
+        markdown = expand_includes(page.markdown, self.root_path, self.max_include_depth)
+        return markdown.rstrip() + "\n"
+
+    def load_page(self, page_id: str) -> Page:
+        """Load a canonical page from disk.
+
+        Args:
+            page_id: Logical page ID.
+
+        Raises:
+            HelpPageNotFoundError: If the page file is missing.
+
+        Returns:
+            Parsed page.
+        """
+        path = self._page_path(page_id)
+        if not path.is_file():
+            raise HelpPageNotFoundError(f"page not found: {page_id}")
+
+        metadata, markdown = parse_front_matter(path.read_text(encoding="utf-8"), path)
+        return Page(page_id=page_id, path=path, metadata=metadata, markdown=markdown)
+
+    def load_book(self, slug: str) -> Book:
+        """Load a book by slug.
+
+        Args:
+            slug: Book slug.
+
+        Raises:
+            HelpBookNotFoundError: If the book file is missing.
+
+        Returns:
+            Parsed book.
+        """
+        path = self._book_path(slug)
+        if not path.is_file():
+            raise HelpBookNotFoundError(f"book not found: {slug}")
+        return parse_book(path)
+
+    def validate_page(self, page_id: str) -> None:
+        """Validate includes, help links, and asset links for one page.
+
+        Args:
+            page_id: Logical page ID.
+
+        Raises:
+            HelpAssetNotFoundError: If an asset reference is missing.
+            HelpLinkNotFoundError: If a help link points to a missing page.
+            HelpPageNotFoundError: If the page file is missing.
+        """
+        markdown = self.render_page(page_id)
+        validate_help_links(markdown, self._page_exists)
+        validate_asset_links(markdown, self.assets_path)
+
+    def validate_book(self, slug: str) -> None:
+        """Validate that all pages referenced by a book exist and pass page validation.
+
+        Args:
+            slug: Book slug.
+
+        Raises:
+            HelpBookNotFoundError: If the book file is missing.
+            HelpPageNotFoundError: If a referenced page is missing.
+        """
+        book = self.load_book(slug)
+        for page_id in book.pages:
+            self.validate_page(page_id)
+
+    def _page_path(self, page_id: str) -> Path:
+        """Return the filesystem path for a safe page ID.
+
+        Args:
+            page_id: Logical page ID.
+
+        Raises:
+            HelpPageNotFoundError: If the page ID is unsafe.
+
+        Returns:
+            Markdown file path.
+        """
+        rel = self._safe_relative(page_id, HelpPageNotFoundError)
+        return self.pages_path / rel.with_suffix(".md")
+
+    def _book_path(self, slug: str) -> Path:
+        """Return the filesystem path for a safe book slug.
+
+        Args:
+            slug: Book slug.
+
+        Raises:
+            HelpBookNotFoundError: If the slug is unsafe.
+
+        Returns:
+            YAML file path.
+        """
+        rel = self._safe_relative(slug, HelpBookNotFoundError)
+        return self.books_path / rel.with_suffix(".yaml")
+
+    def _page_exists(self, page_id: str) -> bool:
+        """Return whether a page ID resolves to an existing file.
+
+        Args:
+            page_id: Logical page ID.
+
+        Returns:
+            True when the page exists.
+        """
+        try:
+            return self._page_path(page_id).is_file()
+        except HelpPageNotFoundError:
+            return False
+
+    @staticmethod
+    def _safe_relative(value: str, error_type: type[Exception]) -> Path:
+        """Convert a logical ID into a safe relative filesystem path.
+
+        Args:
+            value: Logical ID or slug.
+            error_type: Exception class to raise for unsafe values.
+
+        Raises:
+            Exception: The supplied ``error_type`` when ``value`` is unsafe.
+
+        Returns:
+            Relative path.
+        """
+        rel = PurePosixPath(value)
+        if rel.is_absolute() or ".." in rel.parts or not rel.parts or any(part == "" for part in rel.parts):
+            raise error_type(f"unsafe help path: {value}")
+        return Path(*rel.parts)

app_help/exceptions.py

@@ -0,0 +1,50 @@
+"""Exceptions raised by the file-based help engine."""
+
+
+class HelpError(Exception):
+    """Base class for help engine errors."""
+
+
+class HelpPageNotFoundError(HelpError):
+    """Raised when a requested help page does not exist."""
+
+
+class HelpBookNotFoundError(HelpError):
+    """Raised when a requested help book does not exist."""
+
+
+class PageNotInBookError(HelpError):
+    """Raised when a book-scoped page request is not listed in the book."""
+
+
+class InvalidIncludeError(HelpError):
+    """Raised when an include directive points outside allowed snippets."""
+
+
+class IncludeNotFoundError(HelpError):
+    """Raised when an include directive points to a missing snippet."""
+
+
+class CircularIncludeError(HelpError):
+    """Raised when snippet includes form a cycle."""
+
+
+class IncludeDepthError(HelpError):
+    """Raised when snippet includes exceed the configured depth."""
+
+
+class InvalidBookError(HelpError):
+    """Raised when a book YAML file is missing required structure."""
+
+
+class InvalidFrontMatterError(HelpError):
+    """Raised when page front matter is not valid YAML metadata."""
+
+
+class HelpLinkNotFoundError(HelpError):
+    """Raised when a rendered page links to a missing help page."""
+
+
+class HelpAssetNotFoundError(HelpError):
+    """Raised when a rendered page references a missing asset."""
+

app_help/migrations/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

app_help/models.py

@@ -0,0 +1,59 @@
+"""Data models for parsed filesystem help content."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Page:
+    """Canonical Markdown help page loaded from disk.
+
+    Args:
+        page_id: Logical page ID, such as ``billing/overview``.
+        path: Source Markdown file path.
+        metadata: YAML front matter values.
+        markdown: Markdown body with front matter removed.
+    """
+
+    #: Logical page ID, such as ``billing/overview``.
+    page_id: str
+    #: Source Markdown file path.
+    path: Path
+    #: YAML front matter values.
+    metadata: dict[str, Any]
+    #: Markdown body with front matter removed.
+    markdown: str
+
+
+@dataclass(frozen=True)
+class Book:
+    """YAML-defined reading path that references canonical pages.
+
+    Args:
+        slug: Book slug used for lookup.
+        path: Source YAML file path.
+        metadata: Parsed YAML values.
+        pages: Flattened page IDs referenced by all sections.
+    """
+
+    #: Book slug used for lookup.
+    slug: str
+    #: Source YAML file path.
+    path: Path
+    #: Parsed YAML values.
+    metadata: dict[str, Any]
+    #: Flattened page IDs referenced by all sections.
+    pages: tuple[str, ...]
+
+    def contains_page(self, page_id: str) -> bool:
+        """Return whether the book references a page.
+
+        Args:
+            page_id: Logical page ID to find.
+
+        Returns:
+            True when the page appears in any book section.
+        """
+        return page_id in self.pages
+

app_help/parsing.py

@@ -0,0 +1,192 @@
+"""Parsing helpers for Markdown help pages, books, and directives."""
+
+from pathlib import Path, PurePosixPath
+import re
+from typing import Any
+
+import yaml
+
+from app_help.exceptions import (
+    CircularIncludeError,
+    HelpAssetNotFoundError,
+    HelpLinkNotFoundError,
+    IncludeDepthError,
+    IncludeNotFoundError,
+    InvalidBookError,
+    InvalidFrontMatterError,
+    InvalidIncludeError,
+)
+from app_help.models import Book
+
+#: Whole-line include directive matcher.
+INCLUDE_RE = re.compile(r"^::include\s+(.+?)\s*(?:\n|$)", re.MULTILINE)
+#: Markdown help link target matcher.
+HELP_LINK_RE = re.compile(r"\]\(help:([^)#]+)(?:#[^)]+)?\)")
+#: Markdown asset link target matcher.
+ASSET_LINK_RE = re.compile(r"\]\(asset:([^)]+)\)")
+
+
+def parse_front_matter(markdown: str, source: Path) -> tuple[dict[str, Any], str]:
+    """Split YAML front matter from a Markdown document.
+
+    Args:
+        markdown: Raw Markdown file contents.
+        source: Source path used in error messages.
+
+    Raises:
+        InvalidFrontMatterError: If front matter is malformed or not a mapping.
+
+    Returns:
+        Metadata and Markdown body.
+    """
+    lines = markdown.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return {}, markdown
+
+    end_index = None
+    for index, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_index = index
+            break
+
+    if end_index is None:
+        raise InvalidFrontMatterError(f"{source} has unterminated front matter")
+
+    try:
+        metadata = yaml.safe_load("".join(lines[1:end_index])) or {}
+    except yaml.YAMLError as exc:
+        raise InvalidFrontMatterError(f"{source} has invalid front matter") from exc
+
+    if not isinstance(metadata, dict):
+        raise InvalidFrontMatterError(f"{source} front matter must be a mapping")
+
+    return metadata, "".join(lines[end_index + 1 :]).lstrip("\n")
+
+
+def parse_book(path: Path) -> Book:
+    """Parse a YAML help book definition.
+
+    Args:
+        path: Book YAML file path.
+
+    Raises:
+        InvalidBookError: If YAML or book structure is invalid.
+
+    Returns:
+        Parsed book.
+    """
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise InvalidBookError(f"{path} is not valid YAML") from exc
+
+    if not isinstance(data, dict):
+        raise InvalidBookError(f"{path} must contain a YAML mapping")
+
+    sections = data.get("sections", [])
+    if not isinstance(sections, list):
+        raise InvalidBookError(f"{path} sections must be a list")
+
+    pages: list[str] = []
+    for section in sections:
+        if not isinstance(section, dict):
+            raise InvalidBookError(f"{path} section must be a mapping")
+        section_pages = section.get("pages", [])
+        if not isinstance(section_pages, list) or not all(isinstance(page, str) for page in section_pages):
+            raise InvalidBookError(f"{path} section pages must be strings")
+        pages.extend(section_pages)
+
+    slug = data.get("slug", path.stem)
+    if not isinstance(slug, str):
+        raise InvalidBookError(f"{path} slug must be a string")
+
+    return Book(slug=slug, path=path, metadata=data, pages=tuple(pages))
+
+
+def expand_includes(markdown: str, root_path: Path, max_depth: int, depth: int = 0, stack: tuple[Path, ...] = ()) -> str:
+    """Expand snippet include directives in Markdown.
+
+    Args:
+        markdown: Markdown text to expand.
+        root_path: Help root containing the ``snippets`` directory.
+        max_depth: Maximum nested include depth.
+        depth: Current include depth.
+        stack: Include files currently being expanded.
+
+    Raises:
+        CircularIncludeError: If snippets include each other cyclically.
+        IncludeDepthError: If expansion exceeds ``max_depth``.
+        IncludeNotFoundError: If a snippet file is missing.
+        InvalidIncludeError: If an include target is unsafe.
+
+    Returns:
+        Markdown with snippets expanded.
+    """
+
+    def replace(match: re.Match[str]) -> str:
+        target = match.group(1).strip()
+        snippet_path = resolve_include_path(root_path, target)
+
+        if depth >= max_depth:
+            raise IncludeDepthError(f"include depth exceeded at {target}")
+        if snippet_path in stack:
+            raise CircularIncludeError(f"circular include at {target}")
+        if not snippet_path.is_file():
+            raise IncludeNotFoundError(f"include not found: {target}")
+
+        nested = snippet_path.read_text(encoding="utf-8")
+        return expand_includes(nested, root_path, max_depth, depth + 1, stack + (snippet_path,))
+
+    return INCLUDE_RE.sub(replace, markdown)
+
+
+def resolve_include_path(root_path: Path, target: str) -> Path:
+    """Resolve a snippet include target.
+
+    Args:
+        root_path: Help root path.
+        target: Include target from a directive.
+
+    Raises:
+        InvalidIncludeError: If the target is absolute, traverses upward, or is not under snippets.
+
+    Returns:
+        Absolute snippet path.
+    """
+    rel = PurePosixPath(target)
+    if rel.is_absolute() or ".." in rel.parts or not rel.parts or rel.parts[0] != "snippets":
+        raise InvalidIncludeError(f"invalid include target: {target}")
+    return root_path / Path(*rel.parts)
+
+
+def validate_help_links(markdown: str, page_exists: Any) -> None:
+    """Validate ``help:`` links in Markdown.
+
+    Args:
+        markdown: Markdown text to scan.
+        page_exists: Callable accepting a page ID and returning a boolean.
+
+    Raises:
+        HelpLinkNotFoundError: If a linked page does not exist.
+    """
+    for match in HELP_LINK_RE.finditer(markdown):
+        page_id = match.group(1)
+        if not page_exists(page_id):
+            raise HelpLinkNotFoundError(f"help link target not found: {page_id}")
+
+
+def validate_asset_links(markdown: str, assets_path: Path) -> None:
+    """Validate ``asset:`` links in Markdown.
+
+    Args:
+        markdown: Markdown text to scan.
+        assets_path: Help assets directory.
+
+    Raises:
+        HelpAssetNotFoundError: If a referenced asset is missing or unsafe.
+    """
+    for match in ASSET_LINK_RE.finditer(markdown):
+        target = match.group(1)
+        rel = PurePosixPath(target)
+        if rel.is_absolute() or ".." in rel.parts or not (assets_path / Path(*rel.parts)).is_file():
+            raise HelpAssetNotFoundError(f"asset target not found: {target}")

app_help/views.py

@@ -0,0 +1,131 @@
+"""Django view mixins for rendering help content in Wildewidgets views."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, ClassVar
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+from app_help.engine import HelpEngine
+
+
+class HelpOffcanvasMixin:
+    """Wrap Wildewidgets view content with a help offcanvas.
+
+    List this mixin **before** :class:`wildewidgets.StandardWidgetMixin` so
+    cooperative ``get_context_data()`` can descend through
+    ``StandardWidgetMixin`` first (which calls the view's ``get_content()``)
+    and then wrap the resulting ``content`` context value on the way back up.
+
+    Example::
+
+        class PageView(HelpOffcanvasMixin, MenuMixin, StandardWidgetMixin, TemplateView):
+            ...
+
+    The view must provide a ``content`` context value by the time
+    ``super().get_context_data()`` returns.
+    """
+
+    #: Optional filesystem root containing help content.
+    help_root: ClassVar[str | Path | None] = None
+    #: Help book slug used to constrain the rendered page.
+    help_book_slug: ClassVar[str | None] = None
+    #: Help page id to render.
+    help_page_id: ClassVar[str | None] = None
+    #: DOM id used by the help offcanvas and trigger.
+    help_offcanvas_id: ClassVar[str] = "help-offcanvas"
+    #: Header title shown in the help offcanvas.
+    help_offcanvas_title: ClassVar[str] = "Help"
+    #: CSS classes applied around rendered Markdown content.
+    help_markdown_css_class: ClassVar[str] = ""
+
+    def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
+        """Wrap the content context widget with the help offcanvas.
+
+        Keyword Args:
+            **kwargs: Extra context values.
+
+        Raises:
+            ImproperlyConfigured: If no ``content`` context value exists.
+
+        Returns:
+            Context with ``content`` replaced by a wrapping block.
+        """
+        context = super().get_context_data(**kwargs)  # type: ignore[misc]
+        content = context.get("content")
+        if content is None:
+            msg = "HelpOffcanvasMixin requires a content context value."
+            raise ImproperlyConfigured(msg)
+
+        from wildewidgets import Block
+
+        context["content"] = Block(content, self.get_help_offcanvas())
+        return context
+
+    def get_help_root(self) -> str | Path:
+        """Return the help root for the current view.
+
+        Raises:
+            ImproperlyConfigured: If neither ``help_root`` nor ``APP_HELP_ROOT`` is set.
+
+        Returns:
+            Filesystem help root.
+        """
+        root = self.help_root if self.help_root is not None else getattr(settings, "APP_HELP_ROOT", None)
+        if not isinstance(root, str | Path) or root == "":
+            msg = "HelpOffcanvasMixin requires help_root or settings.APP_HELP_ROOT."
+            raise ImproperlyConfigured(msg)
+        return root
+
+    def get_help_page_id(self) -> str:
+        """Return the help page id for the current view.
+
+        Raises:
+            ImproperlyConfigured: If ``help_page_id`` is not set.
+
+        Returns:
+            Help page id.
+        """
+        if not self.help_page_id:
+            msg = "HelpOffcanvasMixin requires help_page_id."
+            raise ImproperlyConfigured(msg)
+        return self.help_page_id
+
+    def get_help_book_slug(self) -> str | None:
+        """Return the optional help book slug.
+
+        Returns:
+            Help book slug, or ``None`` for unscoped page rendering.
+        """
+        return self.help_book_slug
+
+    def get_help_markdown(self) -> str:
+        """Render Markdown for the configured help page.
+
+        Returns:
+            Rendered Markdown with includes expanded.
+        """
+        return HelpEngine(self.get_help_root()).render_page(
+            self.get_help_page_id(),
+            book_slug=self.get_help_book_slug(),
+        )
+
+    def get_help_offcanvas(self) -> Any:
+        """Build the help offcanvas widget.
+
+        Returns:
+            Wildewidgets offcanvas widget containing rendered Markdown.
+        """
+        from wildewidgets import MarkdownWidget, OffcanvasWidget
+
+        markdown = MarkdownWidget(
+            text=self.get_help_markdown(),
+            css_class=self.help_markdown_css_class,
+        )
+        return OffcanvasWidget(
+            offcanvas_id=self.help_offcanvas_id,
+            offcanvas_title=self.help_offcanvas_title,
+            widget=markdown,
+        )

demo/demo/asgi.py

@@ -0,0 +1,16 @@
+"""
+ASGI config for demo project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/6.0/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'demo.settings')
+
+application = get_asgi_application()

demo/demo/core/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.