MkDocs

Dokumentátor jsem zvolil, protože je docela jednoduchý na obsluhu a dokumentaci je možné psát v Markdownu.

Použil jsem MkDocs s rozšířením Material for MkDocs.

Instalace pomocí Dockeru:

docker pull squidfunk/mkdocs-material

Založení adresáře se základním souborem:

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

Spuštění development prostředí:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Sestavení dokumentace do HTML:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material build

Při generování buildu jsem měl problémy, že odkazy v menu odkazovaly na složky a ne na konkrétní HTML stránky. Problém je podepsaný zde.

Řešení bylo přidat do konfiguračního souboru *mkdocs.yml* tuto direktivu:

use_directory_urls: false

Takže konfigurační soubor vypadá například takto:

site_name: FinTailor
nav:
  - Instalace: index.md
  - Poinstalační kroky: after-install.md
  - Databázový model: dbmodel.md
  - Databáze: database.md
  - Vkládání nového leadu: new-lead.md
  - Konfigurační soubory:
      - docker-compose.yml: docker-compose.yml.md
 
use_directory_urls: false

Pro kreslení grafů je potřeba přidat plugin pro Mermaid. Vycházel jsem z dokumentace.

Editoval jsem soubor mkdocs.yml a přidal plugin Mermaid:

site_name: My Documentation
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Pak už stačí přidat kód pro graf Mermaid.

``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

Pro zkoušení možností grafů Mermaid lze použít i Mermaid Live editor. Užitečná může být dokumentace pro kreslení grafů v Mermaidu.

Pro další zkoumání může posloužit ještě tento zdroj: https://mkdocs-mermaid2.readthedocs.io/en/latest/

MkDocs

Konfiguračního soubor mkdocs.yml

Mermaid pro MkDocs

Další zdroje

Wiki