Skip to content

Documentation build and deployment

1. Source layout

English is the default website language. German mirrors every page at the same relative path.

docs/
  en/...
  en/assets/screenshots/...
  de/...
  de/assets/screenshots/...
  assets/screenshot-manifest.json

The root README.md is English; README_DE.md is German. Markdown/MkDocs is the authoritative source. Generated site/ content is not edited manually.

2. Local preview

python -m venv .venv-docs
.\.venv-docs\Scripts\Activate.ps1
pip install -r docs-requirements.txt
python scripts/verify_documentation.py
mkdocs serve

English is available at /, German at /de/. The Material language switcher retains the current relative page.

3. Strict build

mkdocs build --strict --clean

mkdocs-static-i18n uses folder structure with fallback disabled; a missing German counterpart therefore cannot silently display English. mkdocs-redirects preserves the former flat German documentation URLs.

4. Screenshot capture

Run the reproducible capture script from a clean working directory:

.\venv\Scripts\python.exe scripts\capture_documentation_screenshots.py

The script uses an isolated temporary configuration/database, disables external services and writes stable semantic PNG names for en-GB and de-DE. Never point it at state/archive.db or production cloud/source credentials.

The screenshot manifest records locale, feature, file and capture profile. Visual review must verify FLEET Mira branding, no clipped controls and no personal/endpoint/credential data.

5. Verification script

scripts/verify_documentation.py checks:

  • exact DE/EN page-path parity;
  • referenced local images exist;
  • screenshot manifest references valid files;
  • no Windows user paths or common secret patterns;
  • no unapproved legacy visible product names;
  • README language links and required top-level pages.

The script is a guardrail, not a substitute for content/visual review.

6. CI publication

.github/workflows/publish-docs.yml installs pinned documentation dependencies, runs verification and mkdocs build --strict --clean, checks out the public technical documentation repository and replaces its generated content.

DOCS_DEPLOY_TOKEN needs write access only to the destination repository. Pull requests should build but should not publish with an untrusted token context.

The destination repository name may retain the old technical DTCONGDownloadTool-docs identifier. The published site title/content remain FLEET Mira.

7. Authoring rules

  • Update English and German in the same change.
  • Use identical relative page/image paths per language.
  • Describe implemented behaviour only.
  • Use stable IDs/status/API fields verbatim in code formatting.
  • Use FLEET Mira for visible product text; use DLTNG only in explicit legacy compatibility explanations.
  • Localise Mermaid labels, captions and alt text.
  • Do not commit production DDD files, databases, documents, logs, tokens, server names or user paths.
  • Re-run screenshot capture after a visible UI/navigation change.

8. Release checklist

  • [ ] documentation verifier passes;
  • [ ] strict MkDocs build passes;
  • [ ] language switch retains matching page;
  • [ ] old flat URLs redirect;
  • [ ] all screenshots exist in both locales;
  • [ ] README and navigation match current release;
  • [ ] APIs and data contracts match code/version constants;
  • [ ] no secrets or operational data in generated site.