feat(docs): per-application documentation, admin-authored + public (BUNYIP-388) #382
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/BUNYIP-388-application-docs"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Per-application documentation: multiple markdown pages per catalog app, authored by admins and read publicly, rendered through the same pipeline as the global
/docs(markdown with raw HTML stripped). Mokosh Server and Mokosh Web ship with initial docs; every other app starts with none.Layers
20260721000010_create_application_docs.sql:application_docs(multi-page,application_idFK ON DELETE CASCADE, unique per app+slug,sort_order), seeded formokosh-server(Getting Started + Configuration, grounded in its real env config) andmokosh-www(Getting Started). Validated on a throwaway postgres (seed counts, dollar-quoted bodies, cascade).ApplicationDocmodel +ApplicationDocRepository. Public readsGET /v1/applications/{slug}/docsand/{doc_slug}(no auth, 404 on unknown); admin writes (AdminUser) under/v1/admin/applications/{app_id}/docsand/v1/admin/application-docs/{doc_id}./apps/{slug}/docs(index) and/apps/{slug}/docs/{doc_slug}(page), reusingrender_markdown+ docs styling with an empty state and a 404 branch. Admin docs manager at/admin/applications/{id}/docs(list / add / edit / delete), linked from the app edit page; a Documentation link on each catalog card.Verification
Workspace build + clippy + fmt green (SQLX_OFFLINE, pinned rust-builder); 107 bunyip-web tests pass; the migration and repository join queries validated on postgres.
Follow-up (not in scope)
A
has_docsflag on the app response would let the catalog hide the Documentation link for apps that have no pages yet (today it links unconditionally and the index shows an empty state).Adds documentation to each catalog application: multiple markdown pages per app, authored by admins and read publicly, rendered through the same pipeline as the global /docs (markdown with raw HTML stripped). Mokosh Server and Mokosh Web ship with initial docs; every other app starts with none. Data: new migration `20260721000010_create_application_docs.sql` creates `application_docs` (multi-page, `application_id` FK ON DELETE CASCADE, unique per app+slug, `sort_order`) and seeds mokosh-server (Getting Started + Configuration, grounded in its real env config: DATABASE_URL, OIDC_ISSUER/OIDC_AUDIENCE, ENCRYPTION_KEY, CORS_ORIGIN, RUN_MIGRATIONS) and mokosh-www (Getting Started). Validated on a throwaway postgres: seed counts (server 2 / web 1 / others 0), dollar-quoted bodies intact, and cascade delete. Domain + API: `ApplicationDoc` model + `ApplicationDocRepository` (public list/get by slug via a join, admin create/update/delete). Public reads `GET /v1/applications/{slug}/docs` and `/{doc_slug}` take no auth and 404 on an unknown app or page; admin writes (AdminUser) live under `/v1/admin/applications/{app_id}/docs` and `/v1/admin/application-docs/{doc_id}`. Web (bunyip-web): public render pages at `/apps/{slug}/docs` (index) and `/apps/{slug}/docs/{doc_slug}` (page), reusing the existing render_markdown + docs styling, with an empty state and a 404 branch. An admin docs manager at `/admin/applications/{id}/docs` lists pages and supports add / edit / delete, linked from the app edit page ("Manage documentation"); each catalog card gets a Documentation link. Typed API client calls added in api/calls.rs (public) and api/admin.rs (admin). Verified green: workspace build + clippy + fmt (SQLX_OFFLINE, pinned rust-builder); 107 bunyip-web tests pass; the migration and repository join queries validated on postgres. A `has_docs` flag to hide the catalog Documentation link for apps without pages is a natural follow-up. #BUNYIP-388 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>Reword the /apps/{slug}/docs empty state from the flat "No documentation is available for this app yet." to a warmer "Sorry. No docs for this app yet :(". #BUNYIP-388 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>