Stavební dokumentace¶
Před provedením jakýchkoli změn v dokumentaci BeeWare je užitečné ověřit, zda můžete sestavit stávající dokumentaci.
Než začnete vytvářet dokumentaci, připravte si vývojové prostředí.
Musíte mít nainstalovaný interpret Python 3.13 a musí
být dostupný ve vaší cestě (tj. python3.13 musí spustit
interpret Python 3.13).
BeeWare používá tox pro vytváření dokumentace. Následující příkazy
tox musí být spuštěny ze stejného umístění jako soubor tox.ini, který se
nachází v kořenovém adresáři projektu.
Náhled živé dokumentace¶
Pro podporu rychlé úpravy dokumentace má BeeWare režim „živého náhledu“.
Živý náhled se vytvoří s varováními!
Live serve je k dispozici pro opakované aktualizace dokumentace. Během
aktualizace může dojít k problému s označením. Problémy označené jako WARNING
způsobí selhání standardní kompilace, ale live serve je nastaven tak, aby v
konzoli zobrazoval varování a pokračoval v kompilaci. To vám umožňuje opakovat
aktualizace bez nutnosti restartovat živý náhled.
WARNING se liší od ERROR. Pokud zavedete problém, který je považován za
ERROR, živý server selže a bude vyžadovat restart. Nezačne znovu fungovat,
dokud nebude problém WARNING vyřešen.
Spuštění živého serveru:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Tím se vytvoří dokumentace, spustí se webový server pro poskytování dokumentace a bude sledován souborový systém, zda nedošlo k nějakým změnám ve zdrojovém kódu dokumentace.
Po spuštění serveru se v konzoli zobrazí následující výstup:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Otevřete prohlížeč a přejděte na uvedenou adresu URL. Nyní můžete začít s iterací dokumentace. Pokud bude zjištěna změna, dokumentace bude znovu sestavena a všechny prohlížeče, které zobrazují upravenou stránku, budou automaticky aktualizovány.
docs-live je první krok
Spuštění docs-live pro práci s živým serverem je určeno pro počáteční iterace.
Před odesláním žádosti o stažení byste měli vždy spustit lokální sestavení.
Místní sestavení¶
Jakmile dokončíte iterace, budete muset provést lokální sestavení dokumentace. Tento proces sestavení je navržen tak, aby selhal v případě jakýchkoli problémů se značkami. To vám umožní zachytit vše, co jste mohli na živém serveru přehlédnout.
Generování lokální sestavení¶
Pro vytvoření lokální sestavení:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Výstup této sestavení bude umístěn v adresáři _build v kořenovém adresáři
projektu.
Vytvoření lokálně přeložené sestavy¶
Dokumentace BeeWare' je přeložena do několika jazyků. Aktualizace anglické dokumentace mohou způsobit problémy v jiných jazykových verzích. Před odesláním žádosti o stažení je důležité ověřit, zda všechny verze fungují správně.
Chcete-li vygenerovat sestavení všech dostupných překladů:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Výstup každé jazykové sestavy bude umístěn v příslušném adresáři
_build/html/<languagecode>, kde <languagecode> je dvoumístný nebo pětimístný
kód jazyka přidružený ke konkrétnímu jazyku (např. fr pro francouzštinu, it
pro italštinu atd.).
Pokud narazíte na problém s jednotlivou sestavou, můžete ji spustit samostatně
pomocí příkazu tox -e docs-<languagecode>. Chcete-li například sestavit pouze
francouzskou dokumentaci, spusťte:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Výstup jednojazyčné sestavy bude umístěn v adresáři _build.
Kontrola dokumentace¶
Proces sestavení identifikuje problémy s Markdownem, ale BeeWare provádí některé další kontroly stylu a formátování, známé jako „linting“. Chcete-li spustit kontroly lintingu:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Tím se ověří, že dokumentace neobsahuje:
- nefunkční odkazy
- špatně napsaná slova
Pokud je platný pravopis slova identifikován jako chybný, přidejte slovo do
seznamu v docs/spelling_wordlist. Tím se slovo přidá do slovníku kontroly
pravopisu. Při přidávání do tohoto seznamu mějte na paměti:
- Upřednostňujeme americkou pravopisnou normu, s určitými výjimkami pro programátorské slangové výrazy (např. „apps“) a slovesné tvary podstatných jmen (např. „scrollable“).
- Při odkazování na název produktu je třeba používat preferované velká písmena (např. „macOS“, „GTK“, „pytest“, „Pygame“, „PyScript“).
- Pokud je termín používán „jako kód“, měl by být uveden v uvozovkách (
like this) namísto přidání do slovníku.
Jakmile úspěšně vytvoříte dokumentaci, můžete začít psát dokumentaci.