django-app-help 0.1.0__tar.gz

django_app_help-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include app_help/static *
+recursive-include app_help/templates *

django_app_help-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: django-app-help
+Version: 0.1.0
+Author-email: Caltech IMSS ADS <imss-ads-staff@caltech.edu>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: Django>=5.2
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: django-markdownify>=0.9.7
+Requires-Dist: django-wildewidgets>=1.7.2
+Requires-Dist: pytest>=9.1.1
+
+# Django App Help
+
+Filesystem-backed Markdown help for Django applications. Help content lives in your Git repository, deploys read-only with the app, and renders in the browser through [django-wildewidgets](https://github.com/caltechads/django-wildewidgets).
+
+Use it for in-app guidance, workflow documentation, field explanations, and operational notes — not as a full CMS.
+
+## Features
+
+- Canonical Markdown pages under `help/pages/`
+- Audience-specific **books** defined in YAML under `help/books/`
+- Reusable snippets via `::include` directives
+- Cross-page links with `help:` URLs and asset references with `asset:` URLs
+- `HelpEngine` for loading, rendering, and validating content
+- `HelpOffcanvasMixin` to attach a help panel to Wildewidgets views
+
+## Installation
+
+Install the package and its runtime dependencies:
+
+```bash
+pip install django-app-help
+```
+
+Or:
+
+```bash
+uv add django-app-help
+```
+
+Or, from a checkout of this repository:
+
+```bash
+uv sync
+```
+
+Dependencies include Django, PyYAML, django-markdownify, and django-wildewidgets.
+
+## Help content layout
+
+Point Django at a help root directory with this structure:
+
+```text
+help/
+├── books/
+│   ├── user.yaml
+│   └── admin.yaml
+├── pages/
+│   ├── getting-started/
+│   │   └── welcome.md
+│   └── topics/
+│       └── pages.md
+├── snippets/
+│   └── support-contact.md
+└── assets/
+    └── images/
+```
+
+- **Page IDs** are paths under `pages/` without `.md` (for example `getting-started/welcome`).
+- **Books** list page IDs in sections for different audiences. The same page can appear in multiple books.
+- **Snippets** are included in pages with a whole-line directive:
+
+  ```markdown
+  ::include snippets/support-contact.md
+  ```
+
+- **Links** reference other pages and assets:
+
+  ```markdown
+  [Navigation](help:getting-started/navigation)
+  ![Diagram](asset:images/help-diagram.png)
+  ```
+
+Pages may include YAML front matter (`title`, `summary`, `audience`, and so on). The engine strips front matter before rendering.
+
+## Django setup
+
+### Settings
+
+Add the app (optional — there are no database models, but this keeps the integration explicit):
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "markdownify",
+    "wildewidgets",
+    "app_help",
+]
+```
+
+Set the filesystem help root and import the recommended Markdownify settings:
+
+```python
+from pathlib import Path
+
+from app_help.conf import MARKDOWNIFY  # noqa: F401
+
+APP_HELP_ROOT = Path(__file__).resolve().parent / "myapp" / "help"
+```
+
+`app_help.conf.MARKDOWNIFY` whitelists the HTML tags help pages need when rendered through django-markdownify.
+
+### Wildewidgets views
+
+Use `HelpOffcanvasMixin` on a Wildewidgets view. List it **before** `StandardWidgetMixin` so cooperative `get_context_data()` can build page content first, then wrap it with the help offcanvas:
+
+```python
+from app_help.views import HelpOffcanvasMixin
+from wildewidgets import MenuMixin, StandardWidgetMixin
+from django.views.generic import TemplateView
+
+
+class MyPageView(HelpOffcanvasMixin, MenuMixin, StandardWidgetMixin, TemplateView):
+    help_page_id = "getting-started/welcome"
+    help_book_slug = "user"  # optional; omit to skip book membership checks
+    help_offcanvas_title = "Help"
+
+    def get_content(self):
+        # return your Wildewidgets layout
+        ...
+```
+
+Configure help per view with class attributes:
+
+| Attribute | Purpose |
+|-----------|---------|
+| `help_root` | Override `settings.APP_HELP_ROOT` |
+| `help_page_id` | Page to render (required) |
+| `help_book_slug` | Require the page to be listed in this book |
+| `help_offcanvas_id` | DOM id for the offcanvas (default `help-offcanvas`) |
+| `help_offcanvas_title` | Panel title (default `Help`) |
+
+Override `get_help_root()`, `get_help_page_id()`, or `get_help_book_slug()` when the active page depends on the request.
+
+### Programmatic use
+
+Render or validate content without a view:
+
+```python
+from app_help import HelpEngine
+
+engine = HelpEngine("/path/to/help")
+
+markdown = engine.render_page("getting-started/welcome", book_slug="user")
+page = engine.load_page("getting-started/welcome")
+book = engine.load_book("user")
+
+engine.validate_page("getting-started/welcome")
+engine.validate_book("user")
+```
+
+`render_page()` expands snippet includes, strips front matter, and optionally verifies that the page belongs to the requested book.
+
+## Demo
+
+The `demo/` directory is a small Django project that shows help wired into Academy-themed Wildewidgets pages. It installs this package in editable mode and serves sample content from `demo/demo/core/help/`.
+
+### Run the demo
+
+From the repository root:
+
+```bash
+uv sync
+cd demo
+uv sync
+uv run python manage.py runserver
+```
+
+Open http://127.0.0.1:8000/. Each sidebar route renders a static demo page with a help offcanvas:
+
+| Route | Help book | Help page |
+|-------|-----------|-----------|
+| `/` | `user` | `getting-started/welcome` |
+| `/components/` | `user` | `topics/pages` |
+| `/workflow/` | `developer` | `authoring/pages` |
+| `/status/` | `admin` | `admin/validation` |
+
+Browse the Markdown under `demo/demo/core/help/` to see books, pages, snippets, includes, and link patterns in context. `demo/demo/core/views.py` shows how `HelpOffcanvasMixin` composes with `StandardWidgetMixin`.
+
+## Development
+
+Run the library test suite from the repository root:
+
+```bash
+make pytest
+```
+
+Pass extra pytest arguments after the target:
+
+```bash
+make pytest ARGS="tests/test_engine.py -v"
+```

django_app_help-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Django App Help
+
+Filesystem-backed Markdown help for Django applications. Help content lives in your Git repository, deploys read-only with the app, and renders in the browser through [django-wildewidgets](https://github.com/caltechads/django-wildewidgets).
+
+Use it for in-app guidance, workflow documentation, field explanations, and operational notes — not as a full CMS.
+
+## Features
+
+- Canonical Markdown pages under `help/pages/`
+- Audience-specific **books** defined in YAML under `help/books/`
+- Reusable snippets via `::include` directives
+- Cross-page links with `help:` URLs and asset references with `asset:` URLs
+- `HelpEngine` for loading, rendering, and validating content
+- `HelpOffcanvasMixin` to attach a help panel to Wildewidgets views
+
+## Installation
+
+Install the package and its runtime dependencies:
+
+```bash
+pip install django-app-help
+```
+
+Or:
+
+```bash
+uv add django-app-help
+```
+
+Or, from a checkout of this repository:
+
+```bash
+uv sync
+```
+
+Dependencies include Django, PyYAML, django-markdownify, and django-wildewidgets.
+
+## Help content layout
+
+Point Django at a help root directory with this structure:
+
+```text
+help/
+├── books/
+│   ├── user.yaml
+│   └── admin.yaml
+├── pages/
+│   ├── getting-started/
+│   │   └── welcome.md
+│   └── topics/
+│       └── pages.md
+├── snippets/
+│   └── support-contact.md
+└── assets/
+    └── images/
+```
+
+- **Page IDs** are paths under `pages/` without `.md` (for example `getting-started/welcome`).
+- **Books** list page IDs in sections for different audiences. The same page can appear in multiple books.
+- **Snippets** are included in pages with a whole-line directive:
+
+  ```markdown
+  ::include snippets/support-contact.md
+  ```
+
+- **Links** reference other pages and assets:
+
+  ```markdown
+  [Navigation](help:getting-started/navigation)
+  ![Diagram](asset:images/help-diagram.png)
+  ```
+
+Pages may include YAML front matter (`title`, `summary`, `audience`, and so on). The engine strips front matter before rendering.
+
+## Django setup
+
+### Settings
+
+Add the app (optional — there are no database models, but this keeps the integration explicit):
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "markdownify",
+    "wildewidgets",
+    "app_help",
+]
+```
+
+Set the filesystem help root and import the recommended Markdownify settings:
+
+```python
+from pathlib import Path
+
+from app_help.conf import MARKDOWNIFY  # noqa: F401
+
+APP_HELP_ROOT = Path(__file__).resolve().parent / "myapp" / "help"
+```
+
+`app_help.conf.MARKDOWNIFY` whitelists the HTML tags help pages need when rendered through django-markdownify.
+
+### Wildewidgets views
+
+Use `HelpOffcanvasMixin` on a Wildewidgets view. List it **before** `StandardWidgetMixin` so cooperative `get_context_data()` can build page content first, then wrap it with the help offcanvas:
+
+```python
+from app_help.views import HelpOffcanvasMixin
+from wildewidgets import MenuMixin, StandardWidgetMixin
+from django.views.generic import TemplateView
+
+
+class MyPageView(HelpOffcanvasMixin, MenuMixin, StandardWidgetMixin, TemplateView):
+    help_page_id = "getting-started/welcome"
+    help_book_slug = "user"  # optional; omit to skip book membership checks
+    help_offcanvas_title = "Help"
+
+    def get_content(self):
+        # return your Wildewidgets layout
+        ...
+```
+
+Configure help per view with class attributes:
+
+| Attribute | Purpose |
+|-----------|---------|
+| `help_root` | Override `settings.APP_HELP_ROOT` |
+| `help_page_id` | Page to render (required) |
+| `help_book_slug` | Require the page to be listed in this book |
+| `help_offcanvas_id` | DOM id for the offcanvas (default `help-offcanvas`) |
+| `help_offcanvas_title` | Panel title (default `Help`) |
+
+Override `get_help_root()`, `get_help_page_id()`, or `get_help_book_slug()` when the active page depends on the request.
+
+### Programmatic use
+
+Render or validate content without a view:
+
+```python
+from app_help import HelpEngine
+
+engine = HelpEngine("/path/to/help")
+
+markdown = engine.render_page("getting-started/welcome", book_slug="user")
+page = engine.load_page("getting-started/welcome")
+book = engine.load_book("user")
+
+engine.validate_page("getting-started/welcome")
+engine.validate_book("user")
+```
+
+`render_page()` expands snippet includes, strips front matter, and optionally verifies that the page belongs to the requested book.
+
+## Demo
+
+The `demo/` directory is a small Django project that shows help wired into Academy-themed Wildewidgets pages. It installs this package in editable mode and serves sample content from `demo/demo/core/help/`.
+
+### Run the demo
+
+From the repository root:
+
+```bash
+uv sync
+cd demo
+uv sync
+uv run python manage.py runserver
+```
+
+Open http://127.0.0.1:8000/. Each sidebar route renders a static demo page with a help offcanvas:
+
+| Route | Help book | Help page |
+|-------|-----------|-----------|
+| `/` | `user` | `getting-started/welcome` |
+| `/components/` | `user` | `topics/pages` |
+| `/workflow/` | `developer` | `authoring/pages` |
+| `/status/` | `admin` | `admin/validation` |
+
+Browse the Markdown under `demo/demo/core/help/` to see books, pages, snippets, includes, and link patterns in context. `demo/demo/core/views.py` shows how `HelpOffcanvasMixin` composes with `StandardWidgetMixin`.
+
+## Development
+
+Run the library test suite from the repository root:
+
+```bash
+make pytest
+```
+
+Pass extra pytest arguments after the target:
+
+```bash
+make pytest ARGS="tests/test_engine.py -v"
+```

django_app_help-0.1.0/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"]

django_app_help-0.1.0/app_help/apps.py

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

django_app_help-0.1.0/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"],
+        },
+    },
+}

django_app_help-0.1.0/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)

django_app_help-0.1.0/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."""
+

django_app_help-0.1.0/app_help/migrations/__init__.py

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