Jak psát dokumentaci

Dokumentace je součástí repozitáře se zdrojovými kódy, je umístěna v adresáři /docs/. Struktura dokumentace je popsána v krátkosti v dokumentu struktura souborů.

Kromě repozitáře s dokumentací, který chcete přímo editovat je vhodné si stáhnout repozitář iam-docs.git, který obsahuje tuto příručku a umožní vám lokálně vygenerovat html.

Textový editor

Dokumentace je psaná v AsciiDoc formátu, pro editaci je možné použít jakýkoliv textový editor.

Pokud používáte Atom, je dobré doinstalovat pluginy:

  • language-asciidoc

  • asciidoc-assistant

  • asciidoc-image-helper

  • asciidoc-preview

  • autocomplete-asciidoc

Další možností je přímá editace ve webovém rozhraní GitLabu (jedna záložka podporuje editaci, druhá náhled), tento způsob je vhodný pokud chcete přímo upravit stránku v dokumetnaci a kliknete na odkaz na editaci.

Publikování dokumentace

Ruční generování

Pokud jste si stáhli repozitář iam-docs.git, můžete si výsledné html snadno vygenerovat pomocí skriptu make.sh/make-local.sh.

  • make.sh generuje html podle předpisu antora-playbook.yml, stahuje vše z git repozitářů.

  • make-local.sh generuje html podle local-antora-playbook.yml a používá jako zdroje lokální adresáře.

Upravte si local-antora-playbook.yml nebo si vytvořte vlastní. Do antora-playbook.yml zasahujte jen v případě, že chcete přidat nový kus dokumentace na web.

Automatické publikování

Pokud je provedena úprava v master větvi repozitáře iam-docs.git, je automaticky spuštěno přegenerování webu https://doc.czechidm.com Aby se projevily aktualizace i z jiných repozitářů, je automatické generování spouštěno pravidelně každý den v 6:00.