Struktura souborů dokumentace

Antora

Organizace souborů dokumentace je pro generátor Antora určená následující strukturou popsanou v originální dokumentaci https://docs.antora.org/antora/2.3/standard-directories/

Pro každý repozitář používaný v IAM appliance repozitářích se předpokládá umístění dokumentace v /docs/, Adresář s dokumentací lze použít jiný, ale není to doporučeno.

Každý adresář docs musí obsahovat základní strukturu popsanou v dokumentaci generátoru Antora.

Stránky s textem dokumentace jsou uložené v /modules/modul1/pages/, rozcestník - panel na levé straně - je skládán z nav.adoc souborů na které se odkazuje ze souboru antora.yml.

Soubora strukturů

repozitář
  /docs/
    /modules/
      /modul1/
        /pages/
          index.adoc
          page2.adoc
          page3.adoc
        /images/
      /modul2/
        /pages/
        /images/
        /examples/
    antora.yml

Soubor antora.yml je povinný pro každou dokumentaci.

antora.yml

name: iam-docs
title: CzechIAM appliance documentation
version: 1.0
prerelease: -alpha1
display_version: "1.0 alpha1"
start_page: ROOT:index.adoc
nav:
- modules/ROOT/nav.adoc
- modules/build/nav.adoc

Povinné položky v antora.yml jsou name a version, vše ostatní je buď navíc nebo se berou výchozí hodnoty (např. start_page má výchozá hodnotu ROOT:index.adoc).

Minimální antora.yml

name: iam-docs
version: 1.0

Verzování

Pro IAM appliance používáme verzování pomocí git branche. Verze produktu je v samostatné větvi (branch) a umožňuje tak snadno aplikovat případné úpravy bez dopadů do ostatních větví. Tagy se tedy pro verzování produktu nepoužívají.