User Guide System

Opens the application user guide in the user's default browser.

Architecture

The guide content lives in a separate MkDocs Material site (user_guide_docs/) and is hosted on Cloudflare Pages. On app startup a background worker downloads the guide into a local cache so it works offline too.

Cloudflare Pages (gehasoftwarehub-guide)
    version.json   - current version metadata
    guide.zip      - full MkDocs site as a zip archive

Local cache (persistent_data/user_guide/)
    version.json   - cached version metadata
    index.html     - entry point opened by the browser
    ...            - remaining site files

How It Works

1. Startup: MainController starts GuideCacheWorker in a background thread
2. Worker: Fetches version.json from Cloudflare, compares with local cache
3. Download: If a newer version exists, downloads guide.zip and extracts it
4. Help clicked: Lazy-starts a local HTTP server and opens http://127.0.0.1:<port>/ in the default browser. The server serves from the local cache directory.
5. No cache yet: Falls back to the Cloudflare URL (requires internet)

The local HTTP server is necessary because browsers block Web Workers and fetch() on file:// URLs, which would break MkDocs Material search and theme switching. The server runs in a daemon thread, uses an OS-assigned port, and is automatically cleaned up on app exit.

Structure

user_guide_system/
    __init__.py
    README.md
    constants/
        __init__.py
        paths.py                  - PathDef for cache directory and version file
    model/
        __init__.py
        guide_cache_manager.py    - File I/O for the local cache
        guide_cache_worker.py     - QRunnable background worker
        guide_server.py           - Lazy localhost HTTP server for offline docs

Deploying a New Guide Version

1. Edit content in user_guide_docs/docs/
2. Bump the version in user_guide_docs/VERSION
3. Run python user_guide_docs/deploy_user_guide.py

The next time the app starts, it will detect the new version and download it.