Dokumentování softwaru nástrojem Sphinx

Dokumentace je nezbytná, leč často zanedbávaná, součást softwarového produktu, která nejen pomůže produkt prodat, ale také významně usnadní spolupráci jeho tvůrcům.

V našem kurzu se podíváme na nejmodernější princip tvorby a publikování technické dokumentace za pomoci opensourcového nástroje Sphinx Doc.

Cíl kurzu

Účastník kurzu se naučí vytvářet strukturovaný text a používat nástroj Sphinx Doc k jeho převádění do základních výstupních formátů (HTML, PDF), ve kterých lze dokumentaci dodávat uživatelům. Okrajově se také seznámí s dalšími nástroji, které lze na Sphinx napojit.

Po absolvování kurzu by měl účastník být schopen začít dokumentovat svůj SW produkt, avšak cílem kurzu není zabývat se tím, které informace by dokumentace měla obsahovat, ani jak by měla vypadat.

Osnova

  • Seznámení s metodou publikování z jednoho zdroje
  • Představení funkcionality nástroje Sphinx
  • Vytvoření dokumentačního projektu
  • Strukturování obsahu pomocí značkovacího jazyka (syntaxe rST)
  • Konfigurace dokumentačního projektu
  • Sestavení výstupních formátů
  • Ladění HTML výstupu
  • Ladění PDF výstupu
  • Podpora dokumentování API (Python, C++)
  • Rozšíření Sphinx
  • Integrace s dalšími nástroji
  • Hosting dokumentace (jak publikovat na ReadTheDocs)
  • Konzultace

Časová náročnost

Jednodenní kurz ( 10:00 - 17:00).

Vstupní podmínky

Umět zacházet s některým textovým editorem, který umí zvýrazňovat syntaxi (vim, emacs, jEdit, PyCharm, Atom apod.).

Nezbytná je schopnost základní práce v příkazové řádce (instalace programů, pohyb adresářovou strukturou, spouštění programů), angličtina na úrovni čtení technické dokumentace (kurz bude jinak česky).

Výhodou zkušenosti s dokumentováním, vývojovým prostředím (make), programováním v Pythonu nebo jiném jazyce, verzování s Gitem, sázením textu v LaTeX, znalost HTML a CSS.

Pokud máte tu možnost, je vhodné si přinést vlastní menší SW projekt, ke kterému byste potřebovali začít dělat dokumentaci, nebo na němž byste si to chtěli alespoň zkoušet. Pokud tuto možnost nemáte, nevadí - bude k dispozici demo projekt, na kterém si vše budete moci vyzkoušet.

Rozvrh

Datum Čas Místo Lektor Volná místa Cena s DPH Přihlásit