Přeskočit obsah

Jak psát dokumentaci

Tento dokument slouží jako návod pro udržování a rozšiřování této "Home Bible".

1. Cílová skupina: Rodina vs. Admin

Při psaní si vždy uvědom, pro koho píšeš. Máme dvě oddělené sekce:

🟢 Návod pro rodinu (docs/navod_pro_rodinu/)

  • Cíl: Vyřešit problém ("Nejde internet", "Je mi zima") nebo vysvětlit ovládání.
  • Jazyk: Jednoduchý, lidský, bez technického slangu.
  • Styl: Krok za krokem. Používej obrázky a screenshoty tabletu.
  • Příklad: "Pokud nejde internet, zkus vypojit a zapojit tuhle černou krabičku." (Ne "Restartuj WAN interface na pfSense").

🔴 Technické sekce (Infrastruktura, Chytrý dům...)

  • Cíl: Dokumentace pro tebe (Admina) za rok, až zapomeneš, jak to funguje.
  • Jazyk: Technický, přesný. Anglické pojmy jsou OK (VLAN, Gateway, Entity ID).
  • Obsah: IP adresy, porty, yaml konfigurace, schémata zapojení.
  • Příklad: "VLAN 20 (IoT) má DHCP range 192.168.20.100-200 a je izolovaná firewallem."

Dokumentace Serverů (VM / LXC / Fyzické)

Každý server musí mít v dokumentaci uvedenou sekci Správa a Konfigurace, která obsahuje:

  1. Základní Info:
    • Aktuální verze OS/FW: (např. Debian 12.5, TrueNAS Scale 24.10).
    • Datum poslední aktualizace: (Datum kdy byla verze ověřena).
  2. SSH Přístup:
    • Stav: (Povoleno / Zakázáno / Omezeno na IP).
    • Uživatel: (např. root, debian).
    • Klíč: Musí být explicitně uvedeno, zda je autorizován "Homelab SSH Key" (z Bitwardenu).
  3. Monitoring:
    • Je zařízení v Uptime Kuma (dostupnost)?
    • Je nastaven Syslog? Kam posílá logy?
  4. Customizace:
    • Výpis konfiguračních souborů změněných oproti defaultu.
    • Seznam použitých skriptů (např. tteck community scripts) a jejich účel.
    • Cron úlohy a systemd services vytvořené ručně.

2. Nástroje a Formátování

Používáme Markdown s rozšířeními MkDocs Material.

Formátování seznamů

Před každým seznamem (* nebo 1.) musí být prázdný řádek. Jinak se seznam "přilepí" k předchozímu odstavci a nebude se správně formátovat.

Upozornění (Admonitions)

Používej pro zvýraznění důležitých informací.

!!! tip "Tip pro rychlé ovládání"
    Dvojklikem na vypínač u dveří zhasneš celý dům.

!!! danger "Pozor na restart"
    Tento server restartuj pouze, pokud nikdo nesleduje TV!

Schémata (Mermaid)

Pro grafy sítě a toky dat používej Mermaid. Je to "code-based" diagram, takže se dá snadno editovat.

graph TD
    A[Tlačítko] -->|Zigbee| B(Home Assistant)
    B -->|Modbus| C{Rekuperace}
    C -->|On| D[Větrání]

Odkazy na soubory

Pokud dokumentuješ konfiguraci, odkazuj na konkrétní soubory v repozitáři (cesta relativní k umístění stránky — z docs/ o úroveň výš do kořene repa): [konfigurace tlačítek](../appdaemon/apps/apps.yaml)

3. Pravidla údržby

  1. Single Source of Truth: Dokumentace nesmí lhát. Pokud změníš IP adresu v routeru, musíš ji změnit i tady.
  2. Žádná hesla: Do dokumentace v repozitáři NIKDY nepiš ostrá hesla.
    • Špatně: Heslo k wifi je: SuperTajne123
    • Dobře: Heslo k wifi najdeš v Bitwardenu pod heslem "Domácí Wifi".
  3. Snake_case soubory: Soubory pojmenovávej bez diakritiky a mezer (např. jak_psat_dokumentaci.md).
  4. Aktuální stav, ne historie: Dokumentujeme to, co je teď.
    • Špatně: "Původně jsme měli NVR Hikvision, ale 5.2.2026 jsme ho nahradili za Scrypted."
    • Dobře: "Kamery jsou připojeny do Scrypted NVR. Hardware NVR se nepoužívá."
    • Důvod: Historie patří do Git commit message, ne do dokumentace. Dokumentace musí být čistá a jasná pro toho, kdo přijde k hotové věci.

3a. Kam zapisovat jaký typ poznatku

Při aktualizaci dokumentace nejdřív rozhodni, kam informace přirozeně patří.

  • Tematický dokument
  • Patří sem popis toho, jak systém funguje teď.

  • Používej pro architekturu, topologii, provozní postupy, entity, závislosti a aktuální chování.

  • docs/decision_log.md

  • Patří sem trvalá rozhodnutí a lessons learned, které budou důležité i za měsíce.
  • Typicky: proč jsme něco zvolili, jaký trade-off jsme přijali, jaké omezení platí, co jsme se naučili z incidentu.

  • Nepatří sem backlog, wishlist ani rozpracovaný plán změn.

  • docs/todos.md

  • Patří sem otevřená práce, follow-upy, nápady a plánované změny, které ještě nejsou hotové.

  • Pokud je něco teprve zvažovaný krok nebo budoucí úkol, patří to sem spíš než do decision_log.md.

  • Generované _generated.md soubory

  • Patří sem odvozený stav získaný ze skriptů nebo API.
  • Tyto soubory ručně needituj, ale uprav skript nebo zdroj dat a soubor přegeneruj.

Když si nejsi jistý, použij jednoduché pravidlo:

  • co platí teď → tematický dokument
  • proč to tak je / co jsme se naučili → decision_log.md
  • co ještě chybí → todos.md
  • co generuje skript → _generated.md

4. Automatizace a Živá Data

Pokud to jde, neopisuj manuálně seznamy, které se mění (seznam VM, IP adresy, Zigbee mapa).

  • Princip: Preferujeme skripty, které přes API (např. Proxmox API, HA API) vygenerují markdown kód nebo tabulku.
  • Cíl: Dokumentace by měla být "živá". Pokud přidáš kontejner, měl by se (ideálně) v dokumentaci objevit sám při přegenerování.

Spouštění Python skriptů

Pro spouštění Python skriptů vždy používej uv run - zajistí správné virtuální prostředí a závislosti.

# Správně 
uv run python scripts/doc_gen_proxmox.py
uv run python scripts/doc_gen_unifi.py

# Špatně 
python3 scripts/doc_gen_proxmox.py

Proč uv?

uv automaticky:

  • Vytvoří virtuální prostředí (pokud neexistuje)
  • Nainstaluje závislosti z pyproject.toml
  • Spustí skript v izolovaném prostředí

Generátory dokumentace

Skript Účel Výstup
doc_gen_proxmox.py Proxmox VMs, LXCs, storage, health proxmox_generated.md
doc_gen_unifi.py UniFi kompletní síť (switche, APs, WiFi, VLANy) unifi_generated.md
doc_gen_pfsense.py pfSense firewall, DHCP, routing pfsense_generated.md
doc_gen_truenas.py TrueNAS datasety, snapshoty truenas_generated.md
doc_gen_pbs.py PBS zálohy, datastore pbs_generated.md
doc_gen_switches.py Aruba/HPE switch konfigurace (deprecated) switches_generated.md
doc_gen_wan.py WAN/Internet diagnostika wan_generated.md
doc_gen_zigbee.py Zigbee síť (Z2M) zigbee_generated.md
doc_gen_storj.py Storj cloud backup storj_generated.md
backup_configs.py Záloha pfSense, UniFi, switche docs/files/config_backups/

Diagnostika a monitoring

Skript Účel
log_monitor.py AI Log Monitor (běží na Debian serveru)

Loki dotazy a homelab health diagnostika dnes přes Grafana MCP (dříve loki_search.py / check_homelab.py, odstraněny).

5. Práce s Nedodělky (TODO)

Dokumentace není nikdy hotová. Pokud víš, že něco chybí, označ to jasně. Používej !!! todo admonition, aby to svítilo v textu.

!!! todo "Doplnit hesla"
    Tady chybí odkaz na záznam v Bitwardenu pro přístup k NAS.

To nám umožní snadno filtrovat (grep) nedodělané části a postupně je plnit.

Lokální TODO vs. centrální TODO

  • Lokální !!! todo v dokumentu
  • použij, když chybí detail přímo v konkrétní stránce

  • například chybějící screenshot, odkaz na manuál nebo doplnění jedné sekce

  • docs/todos.md

  • použij, když jde o samostatný follow-up napříč systémem nebo o větší úkol

  • například audit IPv6, doplnění monitoringu nebo plánovanou migraci služby

  • Obojí

  • použij jen tehdy, když lokální mezera současně představuje širší provozní nebo projektový follow-up

6. Manuály a Soubory

Je dobrý nápad mít důležité manuály "u sebe" (abychom nebyli závislí na internetu nebo webu výrobce za 10 let).

  • Kam ukládat: Do adresáře docs/manualy/<zarizeni>/ (preferuj skill /manual, který PDF/HTML stáhne, vytvoří MD extrakt a nabídne přilinkování).
  • Formát: PDF + MD extrakt vedle sebe.
  • Odkazování: V textu odkazuj relativní cestou.
    • [Manuál Ecoforest](manualy/ecoforest_ecogeo/manual_control.md)
    • Nebo pomocí ikony: [:material-file-pdf-box: Stáhnout manuál](manualy/ecoforest_ecogeo/manual_control.pdf)

Velikost repozitáře

Nahrávejte jen kritické manuály (kotel, switch, rekuperace). Návody ke každé žárovce nebo zásuvce zbytečně nafouknou git.

7. Zařízení připojená k Internetu/Síti

Každé zařízení, které je připojené do sítě (LAN/WiFi), musí mít v dokumentaci svou "kartu" nebo řádek v tabulce s těmito údaji:

  • Typ zařízení: (např. ESP32, Zigbee senzor, Hikvision kamera)
  • MAC Adresa: Kritické pro DHCP rezervace a identifikaci na switchi.
  • IP Adresa: Statická nebo DHCP rezervace.
  • VLAN: Do které sítě patří (např. IoT = VLAN 40).
  • Web UI: Odkaz na administrační rozhraní (např. http://192.168.40.15) nebo Nginx proxy (https://sluzba.marada.name).
  • Firmware: Odkaz na stránku výrobce pro stažení nového FW.
  • Manuál: Odkaz na PDF (viz sekce 6) nebo link na web výrobce.
  • Konfigurace:
    • Screenshoty: Pokud má zařízení webové rozhraní, udělej screenshoty klíčových nastavení.
    • Záloha:
      • Manuální: Ulož export konfigurace do docs/files/zalohy/[typ]/.
      • Automatická: Pokud zařízení umí posílat zálohy (např. na NAS), uveď to a popiš kam.

Příklad tabulky

Zařízení IP MAC VLAN Poznámka
Zigbee Senzor Kuchyně 192.168.40.15 AA:BB:CC:DD:EE:FF 40 (IoT) Zigbee2MQTT, teplota+vlhkost