Dokumentace

Základní informace

Před zahájením práce vždy informujte komunitu (vytvořením nového problému nebo komentářem k již existujícímu problému). Tím se vyhnete tomu, aby dvě osoby pracovaly na stejné věci, a předejdete konfliktům.

Práce na dokumentaci musí být začleněna do větve main.

Zdrojový kód dokumentace se nachází ve složce support/documentation/content.

Dokumentace je generována pomocí Hugo. Pokud si chcete svou práci prohlédnout, musíte si ji nainstalovat do počítače.

Minimální požadovaná verze pro Hugo je 0.121.0. Testováno bylo s verzí 0.132.2.

Použitý motiv je hugo-theme-relearn. Než začnete upravovat dokumentaci, měli byste si přečíst jeho dokumentaci.

Při vydání nové verze zásuvného modulu nebo při aktualizaci dokumentace správci zásuvných modulů sloučí větev main do větve documentation. Tím se spustí pipelines github a gitlab a aktualizuje se zveřejněná dokumentace.

Překlady

Základním jazykem je angličtina (kód en).

Složka support/documentation/content/en obsahuje pouze anglické dokumentační soubory.

Dokumentace je přeložena pomocí Weblate (viz translation documentation). K tomu používáme nástroj po4a, jak uvidíme dále na této stránce.

Přidání nového jazyka

V souboru support/documentation/config.toml zkopírujte a upravte část [Languages.fr].

Pokud překlady nejsou kompletní, nevadí, pro chybějící řetězce se použije angličtina.

Náhled

Chcete-li zobrazit náhled úprav, spusťte:

hugo serve -s support/documentation/

Poté otevřete prohlížeč na adrese http://localhost:1313/peertube-plugin-livechat/. Tato stránka se automaticky obnoví při každé změně.

Aktualizace lokalizačních souborů a generování překladů dokumentace

Prozatím máte k dispozici pouze anglickou verzi. Chcete-li aktualizovat dokumentační řetězce a generovat překlady, musíte spustit skript doc-translate.sh.

Za tímto účelem se ujistěte, že máte v počítači nainstalován program po4a (verze >= 0.69).

Pro zpracování překladů stačí provést:

npm run doc:translate

Výsledek si pak můžete prohlédnout pomocí příkazu hugo serve -s support/documentation/ a pomocí voliče jazyka.

Psaní dokumentace

Stačí upravit anglické soubory v support/documentation/content/en.

Před odevzdáním pak vždy spusťte npm run doc:translate, aby se změny v českých souborech mohly promítnout do souboru support/documentation/po/livechat.en.pot.

Pro použití aplikačních řetězců můžete použít zkrácený kód livechat_label. Viz zde: Překlad dokumentace.

Je možné zabránit překladu souboru pomocí livechatnotranslation: true v sekci Yaml Font Matter. Viz zde: Překlad dokumentace.

Pro technickou dokumentaci použijte možnost livechatnotranslation. Nechceme, aby byla technická dokumentace překládána, abychom se vyhnuli problémům kvůli špatnému překladu.

Abyste překladatelům usnadnili práci, vyhněte se příliš dlouhým odstavcům.

Prozatím není možné používat tabulky Markdown: překladatelské nástroje je rozbijí.

Když je vydána nová funkce, můžete použít krátký kód livechat_version_notice pro zobrazení infoboxu s verzí, ve které je funkce dostupná. Tento krátký kód bere jako parametr číslo verze. Zde je příklad:

Co když nemohu používat hugo a/nebo po4a?

Stačí upravit anglické soubory markdown a při zadávání žádosti o stažení zadat, že nelze vytvářet překlady.

Zveřejnění

Zveřejnění dokumentace je automatické, jakmile jsou změny začleněny do větve documentation.