Stavební dokumentace¶
Před provedením jakýchkoli změn v dokumentaci BeeWare Docs Tools je užitečné si ověřit, zda můžete vygenerovat stávající dokumentaci.
Než začnete vytvářet dokumentaci, připravte si vývojové prostředí.
Musíte mít nainstalovaný Python 3.13 interpreter a musí být dostupný ve vaší cestě (např. python3.13 musí spustit Python 3.13).
BeeWare Docs Tools používá tox pro generování 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.
Průběžný náhled dokumentace¶
Pro podporu rychlé úpravy dokumentace má BeeWare Docs Tools režim „náhledu“.
Průběžný náhled se vytvoří s varováními!
Pro testování aktualizací dokumentace je k dispozici živý server. Během provádění aktualizací může dojít k chybám ve značkování. Chyby označené jako WARNING způsobí selhání standardního sestavení, živý server je však nastaven tak, aby v konzole zobrazoval varování a zároveň pokračoval v sestavování. To vám umožňuje provádět iterace, aniž byste museli restartovat živý náhled.
WARNING se liší od ERROR. Pokud do systému zavedete problém, který je považován za ERROR, dojde k selhání produkčního serveru a bude nutné jej restartovat. Server se znovu nespustí, dokud nebude problém ERROR vyřešen.
Spuštění lokálního vývojové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 na kterém poběží dokumentace a budou sledovány soubory, 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 zaznamenána změna, dokumentace se přegeneruje 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 lokálním vývojovým serverem je určeno pro počáteční iterace. Před odesláním pull requestu byste měli vždy spustit lokální build.
Lokální build¶
Jakmile dokončíte úpravu dokumentace, budete muset provést lokální build dokumentace. Tento proces 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 lokálním vývojovém serveru přehlédnout.
Generování lokálního buildu¶
Pro vytvoření lokálního buildu:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Výstup tohoto buildu bude umístěn v adresáři _build v kořenovém adresáři projektu.
Vytvoření lokálního přeloženého buildu¶
Dokumentace BeeWare Docs Tools' 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 pull requestu je důležité ověřit, zda všechny verze fungují správně.
Chcete-li vygenerovat build všech dostupných překladů:
(sloveso) $ tox -e docs-all
(sloveso) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Výstup každé jazykového buildu 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 jednotlivým buildem, můžete ho 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ého buildu bude umístěn v adresáři _build.
Kontrola dokumentace¶
Proces sestavení identifikuje problémy s Markdownem, ale BeeWare Docs Tools 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.