Dokumentacja kodu to proces, w którym programista dokumentuje kod. Jest to dobrze znany termin wśród inżynierów. Jeśli tego nie robią, prowadzi to do słabej czytelności kodu i trudnej konserwacji dla innych członków zespołu.
Dokumentacja kodu różni się od dokumentacji projektu, ponieważ ma na celu głównie to, jak działa system, ale te dwa procesy mają coś wspólnego – wymagania użycia profesjonalnego narzędzia. W tym artykule przedstawiam przegląd kilku popularnych narzędzi do tworzenia dokumentacji kodu.
LaTex
LaTeX jest systemem przygotowywania dokumentów do wysokiej jakości składu. Jest najczęściej używany do średnich i dużych dokumentów technicznych lub naukowych, ale może być używany do prawie każdej formy publikacji.
LaTeX nie jest edytorem tekstu! Zamiast tego LaTeX zachęca autorów, by nie przejmowali się zbytnio wyglądem swoich dokumentów, lecz skupili się na uzyskaniu właściwej treści.
LaTeX jest wysokiej jakości systemem składu; zawiera funkcje zaprojektowane z myślą o tworzeniu dokumentacji technicznej i naukowej. LaTeX jest de facto standardem dla komunikacji i publikacji dokumentów naukowych. LaTeX jest dostępny jako wolne oprogramowanie.
Nie musisz płacić za używanie LaTeXa, tzn, nie ma opłat licencyjnych itp.
Pandoc
Pandoc rozumie szereg przydatnych rozszerzeń składni markdown, w tym metadane dokumentu (tytuł, autor, data); przypisy; tabele; listy definicyjne; indeks górny i dolny; skreślenia; rozszerzone listy uporządkowane (numer początkowy i styl numeracji są istotne); listy przykładów działania; delimitowane bloki kodu z kolorowaniem składni; inteligentne cudzysłowy, myślniki i elipsy; markdown wewnątrz bloków HTML; oraz inline LaTeX. Jeśli pożądana jest ścisła zgodność z markdown, wszystkie te rozszerzenia można wyłączyć.
Istnieje wiele sposobów na dostosowanie Pandoca do własnych potrzeb, w tym system szablonów i potężny system pisania filtrów.
Pandoc zawiera bibliotekę Haskella i samodzielny program wiersza poleceń. Biblioteka zawiera osobne moduły dla każdego formatu wejściowego i wyjściowego, więc dodanie nowego formatu wejściowego lub wyjściowego wymaga jedynie dodania nowego modułu.
Pandoc jest wolnym oprogramowaniem, wydanym na licencji GPL.
Markdown
Markdown jest narzędziem do konwersji tekstu na HTML, przeznaczonym dla autorów stron internetowych. Markdown pozwala pisać w łatwym do czytania i pisania formacie zwykłego tekstu, a następnie konwertować go na poprawny strukturalnie XHTML (lub HTML).
Nadrzędnym celem składni formatowania Markdown jest uczynienie jej jak najbardziej czytelną. W założeniu dokument sformatowany w Markdownie powinien być możliwy do opublikowania w stanie, w jakim się znajduje, jako zwykły tekst, bez widocznych znaczników czy instrukcji formatowania. Podczas gdy na składnię Markdown miało wpływ kilka istniejących filtrów text-to-HTML, największym źródłem inspiracji dla składni Markdown jest format zwykłego tekstu wiadomości e-mail.
LiveEdu
LiveEdu pozwala na nadawanie dokumentacji kodu i tworzenie „dokumentacji kodu wideo.”
Education Ecosystem to zdecentralizowany ekosystem edukacyjny, który uczy profesjonalistów i studentów szkół wyższych, jak budować prawdziwe produkty. Możesz opisać nasz produkt jako hybrydę Pluralsight i Twitch. Budujemy największy na świecie ekosystem nauczania dla przyszłych tematów technologicznych, takich jak sztuczna inteligencja, cyberbezpieczeństwo, rozwój gier, nauka o danych, kryptowaluty i programowanie. Ekosystem edukacyjny jest oparty na wideo, a każdy projekt zawiera wideo, ustrukturyzowany zarys projektu, repo projektu i zasoby do pobrania. Użytkownicy mogą klonować zasoby projektu z Education Ecosystem Git i uruchamiać aplikacje na swoich lokalnych maszynach.
Sphinx
Sphinx to narzędzie, które ułatwia tworzenie inteligentnej i pięknej dokumentacji, napisane przez Georga Brandla i licencjonowane na licencji BSD.
Zostało pierwotnie stworzone dla dokumentacji Pythona i ma doskonałe udogodnienia dla dokumentacji projektów oprogramowania w wielu językach. Oto kilka cech:
- Formaty wyjściowe: HTML (w tym Windows HTML Help), LaTeX (dla drukowalnych wersji PDF), ePub, Texinfo, strony podręcznika, zwykły tekst.
- Rozbudowane odsyłacze: semantyczne znaczniki i automatyczne odnośniki dla funkcji, klas, cytatów, terminów słownikowych i podobnych informacji.
- Struktura hierarchiczna: łatwe definiowanie drzewa dokumentu, z automatycznymi odnośnikami do rodzeństwa, rodziców i dzieci.
.