feat(docs): add built-in help section with How-To guides embedded in app

- Add MkDocs Material docs build stage to Dockerfile and Dockerfile.local
- Mount pre-built docs as static files at /help/ in FastAPI (app/main.py)
- Add app/views/help.py with /help → /help/ permanent redirect route
- Register help router in app/views/__init__.py
- Add Help nav link to base.html (public + app nav, desktop + mobile)
- Create how-to guides: HP printer, ScanSnap, watched folder, email ingestion, mobile scanning
- Update mkdocs.yml with How-To Guides section and Material theme palette
- Add optional docs service (squidfunk/mkdocs-material) to docker-compose.yaml with docs profile
- Add mkdocs-material to requirements-dev.txt
- Add /docs_build to .gitignore
- Add tests for help view (8 tests, 100% coverage on help.py)

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-03-07 20:33:10 +00:00
parent 6ebf66275c
commit 46b2f17acc
17 changed files with 1225 additions and 0 deletions
+26
View File
@@ -76,6 +76,12 @@
{% if request and request.url.path == '/about' %}aria-current="page"{% endif %}>
About
</a>
<a href="/help/"
class="px-3 py-2 rounded-md text-sm font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-100"
title="Help &amp; How-To Guides"
{% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
<i class="fas fa-circle-question mr-1 text-gray-400" aria-hidden="true"></i>Help
</a>
{% else %}
{# ── App nav (logged-in or single-user / auth-disabled mode) ────── #}
@@ -171,6 +177,14 @@
<i class="fas fa-circle-dot mr-0.5" aria-hidden="true"></i> Status
</a>
<!-- Help documentation visible to all users -->
<a href="/help/"
class="px-3 py-2 rounded-md text-sm font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-100"
title="Help &amp; How-To Guides"
{% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
<i class="fas fa-circle-question mr-1 text-gray-400" aria-hidden="true"></i>Help
</a>
{% endif %}{# end multi_user_enabled / is_logged_in check #}
<!-- Dark mode toggle -->
@@ -229,6 +243,11 @@
{% if request and request.url.path == '/about' %}aria-current="page"{% endif %}>
<i class="fas fa-info-circle mr-2 text-gray-400" aria-hidden="true"></i>About
</a>
<a href="/help/"
class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50"
{% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
<i class="fas fa-circle-question mr-2 text-gray-400" aria-hidden="true"></i>Help
</a>
{% else %}
{# ── App links (logged-in or single-user) ────────────────────── #}
@@ -298,6 +317,13 @@
<i class="fas fa-circle-dot mr-1" aria-hidden="true"></i> Status
</a>
<!-- Help documentation -->
<a href="/help/"
class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50"
{% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
<i class="fas fa-circle-question mr-2 text-gray-400" aria-hidden="true"></i>Help
</a>
{% endif %}{# end multi_user_enabled / is_logged_in check #}
<!-- Dark mode toggle (mobile) -->