domverse/photoanalyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

US09-01 — Serve the Documentation Inside the Application #102

New Issue
Closed
opened 2026-08-23 15:06:14 +02:00 by domverse · 3 comments
domverse commented 2026-08-23 15:06:14 +02:00
Owner
Copy Link

Source specification: delivery_backlog/stories/US09-01-docs-in-app.md

US09-01 — Serve the Documentation Inside the Application

Epic: E09

As an operator who was handed a URL and an access secret, I want the manuals inside the
application I am looking at, so that understanding it does not require a repository
checkout or an internet connection.

Acceptance criteria

  • Documentation lives as markdown under docs/, with an index that names every page and
    the order it is meant to be read in. The same files render on Gitea without
    modification.
  • The application serves a /docs view reachable from the main navigation, listing the
    pages and rendering the selected one.
  • Rendering uses a vendored, version-pinned markdown library committed under
    frontend/js/vendor/. It is not fetched from a CDN, not bundled by a build step, and
    not written by hand. The build records the version and a checksum of the vendored file.
  • Diagrams written as mermaid fenced blocks render as diagrams. Mermaid is vendored
    the same way.
  • script-src in the Content-Security-Policy is unchanged: no 'unsafe-eval', no
    'unsafe-inline'. Only style-src gains 'unsafe-inline', and the reason is recorded
    where the policy is defined.
  • Links between documents work in the app: a relative ../foo.md#section link navigates
    to that page and heading rather than downloading a file or leaving the application.
    Every heading has a stable anchor, and a deep link to an anchor scrolls to it.
  • An unknown page renders a documentation-specific not-found message with a link back to
    the index, and never exposes a filesystem path.
  • Documentation is readable without an access secret or behind the same session as
    the rest of the application — whichever is chosen is stated explicitly in the story's
    implementation notes and covered by a test, because an operator locked out by a
    configuration mistake is exactly who needs the troubleshooting page.
  • The view works with no outbound network access at all.

Automated tests

  • Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of
    relative markdown links into in-app routes.
  • Integration: every markdown file under docs/ is reachable from the index; every
    internal link in every document resolves to a file and, where an anchor is given, to a
    heading that exists; the vendored library files match their recorded checksums.
  • Browser: the documentation view renders a page, follows an internal link, deep-links to
    an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an
    unknown page — all with zero console errors and zero CSP violations, asserted, not
    eyeballed.

Dependencies

  • None beyond the delivered application.
Source specification: [delivery_backlog/stories/US09-01-docs-in-app.md](https://git.domverse-berlin.eu/domverse/photoanalyzer/src/branch/main/delivery_backlog/stories/US09-01-docs-in-app.md) # US09-01 — Serve the Documentation Inside the Application Epic: [E09](../E09-documentation.md) As an operator who was handed a URL and an access secret, I want the manuals inside the application I am looking at, so that understanding it does not require a repository checkout or an internet connection. ## Acceptance criteria - Documentation lives as markdown under `docs/`, with an index that names every page and the order it is meant to be read in. The same files render on Gitea without modification. - The application serves a `/docs` view reachable from the main navigation, listing the pages and rendering the selected one. - Rendering uses a vendored, version-pinned markdown library committed under `frontend/js/vendor/`. It is not fetched from a CDN, not bundled by a build step, and not written by hand. The build records the version and a checksum of the vendored file. - Diagrams written as ```mermaid``` fenced blocks render as diagrams. Mermaid is vendored the same way. - `script-src` in the Content-Security-Policy is unchanged: no `'unsafe-eval'`, no `'unsafe-inline'`. Only `style-src` gains `'unsafe-inline'`, and the reason is recorded where the policy is defined. - Links between documents work in the app: a relative `../foo.md#section` link navigates to that page and heading rather than downloading a file or leaving the application. Every heading has a stable anchor, and a deep link to an anchor scrolls to it. - An unknown page renders a documentation-specific not-found message with a link back to the index, and never exposes a filesystem path. - Documentation is readable without an access secret **or** behind the same session as the rest of the application — whichever is chosen is stated explicitly in the story's implementation notes and covered by a test, because an operator locked out by a configuration mistake is exactly who needs the troubleshooting page. - The view works with no outbound network access at all. ## Automated tests - Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of relative markdown links into in-app routes. - Integration: every markdown file under `docs/` is reachable from the index; every internal link in every document resolves to a file and, where an anchor is given, to a heading that exists; the vendored library files match their recorded checksums. - Browser: the documentation view renders a page, follows an internal link, deep-links to an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an unknown page — all with **zero console errors and zero CSP violations**, asserted, not eyeballed. ## Dependencies - None beyond the delivered application.
domverse self-assigned this 2026-08-23 15:06:14 +02:00
domverse added this to the E09 — Product Documentation milestone 2026-08-23 15:07:40 +02:00
domverse added this to the Photo Analyzer Delivery project 2026-08-23 15:08:04 +02:00
domverse added a new dependency 2026-08-23 15:09:52 +02:00
#103 US09-02 — Write the Installation and Operations Manual
domverse added a new dependency 2026-08-23 15:10:17 +02:00
#104 US09-03 — Write the Architecture Overview
domverse added a new dependency 2026-08-23 15:10:18 +02:00
#105 US09-04 — Write the User Manual with Generated Screenshots
domverse added a new dependency 2026-08-23 15:10:18 +02:00
#106 US09-05 — Automate Documentation Acceptance
domverse removed their assignment 2026-08-23 15:15:03 +02:00
domverse added status/in-progress and removed status/ready labels 2026-08-23 15:15:22 +02:00
domverse self-assigned this 2026-08-23 15:15:23 +02:00
domverse commented 2026-08-23 15:15:24 +02:00
Author
Owner
Copy Link

Claimed for implementation on branch us/US09-01-serve-the-documentation-inside-the-application.

Claimed for implementation on branch `us/US09-01-serve-the-documentation-inside-the-application`.
domverse added status/review and removed status/in-progress labels 2026-08-23 21:09:23 +02:00
domverse commented 2026-08-23 21:09:24 +02:00
Author
Owner
Copy Link

Submitted for review: #107

Tests passed:

  • work_item/scripts/python -m unittest discover -s work_item/tests -v
  • work_item/scripts/python -m pytest tests -q
  • work_item/scripts/python -m pytest tests/integration/test_documentation.py tests/e2e/test_docs_ui.py -q
Submitted for review: https://git.domverse-berlin.eu/domverse/photoanalyzer/pulls/107 Tests passed: - `work_item/scripts/python -m unittest discover -s work_item/tests -v` - `work_item/scripts/python -m pytest tests -q` - `work_item/scripts/python -m pytest tests/integration/test_documentation.py tests/e2e/test_docs_ui.py -q`
domverse added status/done and removed status/review labels 2026-08-23 21:09:47 +02:00
domverse commented 2026-08-23 21:09:48 +02:00
Author
Owner
Copy Link

Completed and merged via PR #107.

Completed and merged via PR #107.
domverse moved this to Done in Photo Analyzer Delivery on 2026-08-23 21:18:23 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/backend
Backend services, jobs, or API
 area/database
Schema, persistence, migration, or queries
 area/documentation
Manuals, architecture notes, and in-app documentation
 area/filesystem
Filesystem identity, mutation, or storage
 area/frontend
Browser UI and client-side application
 area/integration
External tools or provider integrations
 area/testing
Automated test suites, fixtures, and tooling
 priority/critical
Release-blocking safety or correctness
 priority/high
Important phase outcome
 priority/normal
Normal planned work
 status/backlog
Awaiting dependency eligibility or prioritization
 status/blocked
Cannot proceed without an explicit resolution
 status/done
Merged, tested, and completed
 status/in-progress
Currently being implemented
 status/ready
Eligible to be claimed
 status/review
Submitted in a pull request for review
 type/documentation
Written documentation delivered as a product artefact
 type/feature
User-facing or domain capability
 type/hardening
Security, resilience, operations, or release hardening
 type/migration
Donor extraction, migration, or legacy consolidation
 type/test
Automated test infrastructure or acceptance coverage
No Label area/documentation area/frontend priority/normal status/done type/feature
Milestone
No items
No Milestone E09 — Product Documentation
Projects
Clear projects
No project Photo Analyzer Delivery
Assignees
Clear assignees
domverse
No Assignees domverse
1 Participants
Notifications
Due Date
No due date set.
Blocks
#103 US09-02 — Write the Installation and Operations Manual
domverse/photoanalyzer
#104 US09-03 — Write the Architecture Overview
domverse/photoanalyzer
#105 US09-04 — Write the User Manual with Generated Screenshots
domverse/photoanalyzer
#106 US09-05 — Automate Documentation Acceptance
domverse/photoanalyzer
Reference: domverse/photoanalyzer#102
Delete Branch "%!s()"

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?