Slate (Slatedocs) - dokumentace API

Hledal jsem vhodná nástroj na dokumentaci jednoduchého API. Nabízí se hned několik nástrojů, nicméně Slate má pro mě jednu velkou výhodu. Všechno budu mít v jednom souboru a napsané v Markdownu. Díky tomu budu moct srozumitelně nakopírovat dokumentaci do ChatGPT.

Pro uživatele je pak možné vygenerovat dokumentaci jako HTML webovou stránku.

Slate funguje tak, že je potřeba vytvořit prostředí, které přeloží Markdown do vizuálně hezké HTML podoby. To je bezvadné pro psaní (development) dokumentace. Pokud jsem s podobou dokumentace spokojený, tak provedu build a vygeneruje se mi HTML webová stránka bez Markdownu.

Zde je odkaz na kontejner v Dockeru: https://hub.docker.com/r/slatedocs/slate

Stačí jednoduše nainstalovat.

docker pull slatedocs/slate

Vytvořil jsem si adresář Slate a v něm tyto dvě složky:

build
source

Do složky src jsem nahrál obsah celé složky source ze vzorové dokumentace.

V Dockeru pak spustím:

root@zenbook:/home/nosek/software/slate# docker run --rm --name slate -p 4567:4567 -v $(pwd)/source:/srv/slate/source slatedocs/slate serve

Pak stačí načíst dokumentaci v prohlížeči na adrese:

http://127.0.0.1:4567

K buildu stačí spustit tento příkaz v Docekeru a HTML dokumentaci najdu ve složce build.

docker run --rm --name slate -v $(pwd)/build:/srv/slate/build -v $(pwd)/source:/srv/slate/source slatedocs/slate build

• Použití Slate v Dockeru