Help deep links — ⓘ ikony v UI → konkrétní docs stránka¶

Audience: vendor app developers + platform UI developers

Cíl: kontextový help v každém formuláři / tlačítku. Klik na ⓘ otevře přesnou sekci v docs (např. docs.avaxis.cz/spec/apps-gateway/#7-service-tokens).

Architektura¶

UI (CustomTkinter)                 docs.avaxis.cz
   │                                       │
   ▼                                       ▼
ⓘ ikona                            stable URL + anchor
 (help_icon helper)                   pages/sections
   │                                       │
   ├── key z registru                      ├── markdown s explicit
   │   (centralized mapping)               │   anchors `{ #id }`
   └── click → webbrowser.open ───────────▶

URL konvence¶

https://docs.avaxis.cz/<area>/<topic>/             # stránka
https://docs.avaxis.cz/<area>/<topic>/#<anchor>    # konkrétní sekce

Příklady: - user-guide/launcher/synchronizace/#přidání-složky - spec/apps-gateway/#7-service-tokens-m2m-oauth2-client_credentials - apps/mzdy/vypocet/#input-hruba-mzda

Anchor konvence v markdownu¶

MkDocs Material auto-generuje anchory z H2/H3 titulků (např. ## Foo bar → #foo-bar). To je fragile — pokud někdo přejmenuje H2, deep link se rozbije. Vendor MUST používat explicit anchory:

# Hlavní stránka

## Přidání složky { #add-folder }

Tady je obsah...

## Odebrání složky { #remove-folder }

...

### Detail kroku { #remove-folder-step-2 }

Pak docs.avaxis.cz/user-guide/launcher/sync/#add-folder je stabilní i pokud někdo přejmenuje "Přidání složky" na "Jak přidat složku".

Launcher2 implementace¶

Centralni registr desktop/launcher2/help_registry.json:

{
  "_admin": {
    "apps.gateway_toggle": {
      "doc_path": "user-guide/admin/aplikace-gateway/#aktivace-gateway",
      "hint": "Aktivuje routing přes apps-gateway, plus health probe."
    }
  }
}

V UI kódu (launcher2 screens/*.py):

from help_widget import help_icon

row = ctk.CTkFrame(parent)
ctk.CTkLabel(row, text="Gateway:").pack(side="left")
ctk.CTkCheckBox(row, ...).pack(side="left")
help_icon(row, key="apps.gateway_toggle")  # ⓘ ikona, registry lookup

help_icon helper: - Vyrobí malou ⓘ ikonu (CTkLabel s emoji) - Hover → tooltip s hint z registry - Klik → webbrowser.open(docs.avaxis.cz/<doc_path>)

Vendor app implementace (přes SDK)¶

Avaxis SDK má identický helper:

import customtkinter as ctk
from avaxis_sdk import help_icon

row = ctk.CTkFrame(parent)
ctk.CTkLabel(row, text="Hrubá mzda:").pack(side="left")
ctk.CTkEntry(row, ...).pack(side="left")
help_icon(row,
          doc_path="apps/mzdy/vypocet/#input-hruba-mzda",
          inline_hint="Mzda před zdaněním a SP/ZP")

Vendor může mít vlastní help_registry.json v repo (pattern jako launcher) nebo používat inline doc_path= argumenty.

Pro koho kde¶

UI element	Kdy přidat ⓘ
Formulářové pole (input, dropdown, checkbox)	Vždy pokud není self-explanatory
Akční tlačítka (Submit, Delete, ...)	Pro destructive akce (delete, revoke)
Sekce headers v dialozích	Pro feature explainery
Status badges (error/warning)	Když user vidí chybu — link na "co to znamená"
Settings options	Vždy
Tooltip-only místa	Pokud máš krátký inline hint, nemusíš plus ⓘ

Co NE¶

❌ ⓘ na trivial labels ("Email:", "Heslo:")
❌ ⓘ na tlačítka co dělají obvious věc (Cancel, Zavřít)
❌ Hardcoded webbrowser.open("https://docs.avaxis.cz/...") v UI kódu bez registry — non-discoverable

Backend URL override pro dev¶

Default je https://docs.avaxis.cz. Pro avaxdev LAN testování:

export AVAX_DOCS_URL="http://192.168.1.55/docs"
python main.py  # launcher2 dev

ⓘ ikony pak otevírají dev hosting místo produkce.

Validace anchors (CI lint)¶

Plánováno: tools/lint_help_registry.py co po MkDocs build skenuje site HTML a ověří že všechny doc_path z help_registry.json reálně existují (stránka + anchor). Pokud chybí → CI fail.

Bez tohoto lintu je fragile: vendor refactor docs můžete zlomit registry silently. TODO pro 1.x.

Související¶

SDK helper: tools/avax-app-template/src/avaxis_sdk.py (function help_icon)
Launcher helper: desktop/launcher2/help_widget.py + registry
Spec MkDocs config: mkdocs.yml
URL konvence: spec platform-docs.md