Dokumentace kódu je proces, při kterém programátor dokumentuje kód. Mezi inženýry je to dobře známý termín. Pokud to nedělají, vede to ke špatné čitelnosti kódu a obtížné údržbě pro ostatní členy týmu.
Dokumentace kódu se liší od projektové dokumentace, protože je zaměřena především na to, jak systém funguje, ale tyto dva procesy mají něco společného – požadavky na používání profesionálních nástrojů. V tomto článku uvádím přehled některých populárních nástrojů pro tvorbu kódové dokumentace.
LaTex
LaTeX je systém pro přípravu dokumentů pro kvalitní sazbu. Nejčastěji se používá pro středně rozsáhlé až rozsáhlé technické nebo vědecké dokumenty, ale lze jej použít téměř pro jakoukoli formu publikování.
LaTeX není textový procesor! Místo toho LaTeX nabádá autory, aby se příliš nestarali o vzhled svých dokumentů, ale soustředili se na správný obsah.
LaTeX je vysoce kvalitní systém pro sazbu; obsahuje funkce určené pro tvorbu technické a vědecké dokumentace. LaTeX je de facto standardem pro komunikaci a publikování vědeckých dokumentů. LaTeX je k dispozici jako svobodný software.
Za používání LaTeXu nemusíte platit, tzn, nejsou zde žádné licenční poplatky apod.
Pandoc
Pandoc rozumí řadě užitečných rozšíření syntaxe markdown, včetně metadat dokumentu (název, autor, datum); poznámek pod čarou; tabulek; definičních seznamů; horního a dolního indexu; přeškrtávání; rozšířených uspořádaných seznamů (významné je počáteční číslo a styl číslování); seznamů běžících příkladů; ohraničených bloků kódu se zvýrazněním syntaxe; inteligentních uvozovek, pomlček a elips; markdown uvnitř bloků HTML a inline LaTeXu. Pokud je požadována přísná kompatibilita s markdownem, lze všechna tato rozšíření vypnout.
Pandoc lze mnoha způsoby přizpůsobit svým potřebám, včetně systému šablon a výkonného systému pro psaní filtrů.
Pandoc obsahuje knihovnu Haskell a samostatný program příkazového řádku. Knihovna obsahuje samostatné moduly pro každý vstupní a výstupní formát, takže přidání nového vstupního nebo výstupního formátu vyžaduje pouze přidání nového modulu.
Pandoc je svobodný software vydaný pod licencí GPL.
Markdown
Markdown je nástroj pro převod textu do HTML pro autory webových stránek. Markdown umožňuje psát pomocí snadno čitelného a přehledného formátu prostého textu a následně jej převést na strukturně validní XHTML (nebo HTML).
Předním cílem návrhu formátovací syntaxe Markdown je, aby byla co nejčitelnější. Jde o to, aby dokument ve formátu Markdown bylo možné publikovat tak, jak je, jako prostý text, aniž by vypadal, že byl označen značkami nebo formátovacími pokyny. Syntaxe Markdown byla sice ovlivněna několika existujícími filtry pro převod textu do jazyka HTML, ale největším zdrojem inspirace pro syntaxi Markdown je formát prostého textového e-mailu.
LiveEdu
LiveEdu umožňuje vysílat dokumentaci kódu a vytvářet „dokumentaci videokódu“.
Education Ecosystem je decentralizovaný vzdělávací ekosystém, který učí profesionály a studenty vysokých škol, jak vytvářet skutečné produkty. Náš produkt můžete popsat jako hybrid Pluralsight a Twitch. Budujeme největší vzdělávací ekosystém na světě pro technologická témata budoucnosti, jako je umělá inteligence, kybernetická bezpečnost, vývoj her, datová věda, kryptoměny a programování. Vzdělávací ekosystém je založen na videích a každý projekt obsahuje videa, strukturovanou osnovu projektu, repozitář projektu a zdroje ke stažení. Uživatelé mohou klonovat zdroje projektů z Education Ecosystem Git a spouštět aplikace na svém lokálním počítači.
Sphinx
Sphinx je nástroj, který usnadňuje vytváření inteligentní a krásné dokumentace, napsal jej Georg Brandl a je licencován pod licencí BSD.
Původně byl vytvořen pro dokumentaci jazyka Python a má vynikající možnosti pro dokumentaci softwarových projektů v řadě jazyků.