Witajcie, w dzisiejszym wpisie chciałbym przedstawić Wam jedno z narzędzi przydatne przy tworzeniu projektów (i to nie tylko typowo webowych). Bohaterem dzisiejszego wpisu będzie TypeFriendly, czyli generator dokumentacji, manuali czy podręczników.
TypeFriendly to skrypt PHP działający w konsoli (CLI), napisany przez Tomasza „Zyxa” Jędrzejewskiego. Jest dostępny jako open source. Autor przedstawił inne podejście do tworzenia dokumentacji niż autorzy np. phpDocumentatora (phpDoc). Zamiast bazowania na setkach komentarzy porozrzucanych po plikach PHP i opisujących poszczególne zmienne, funkcje, metody czy klasy, TypeFriendly generuje dokumentację na bazie plików w specjalnym formacie – jednakże tworzonych w całości przez użytkownika. To powoduje, że może być on wykorzystywany nie tylko do PHP lub w ogóle nie do programowania – można w nim po prostu stworzyć dowolny podręcznik.
Materiał wejściowy dla skryptu to zbiór plików *.txt o ustandaryzowanych nazwach i zawartości opisywanej za pomocą składni Markdown z pewnymi ulepszeniami i dodatkami. Autor bardzo intuicyjnie przewidział tworzenie poszczególnych rozdziałów z nieskończoną ilością zagnieżdżeń, tworzenie linkowania pomiędzy nimi oraz takich elementów jak spisu treści. Większość elementów nawigacyjnych jest generowana automatycznie na podstawie pewnych szczególnych tagów dodawanych do każdego pliku oraz nazw tych plików.
Składnia Mardown została wzbogacona o możliwości, które mogą okazać się przydatne przy tworzeniu różnego rodzaju manuali – między innymi automatyczne kolorowanie kodu z użyciem GeSHi czy wstawianie różnego rodzaju wskazówek, ostrzeżeń czy informacji do tekstu.
Skrypt wspiera bezproblemowo opcję tworzenia dokumentacji w wielu językach. Dużym plusem jest też fakt, iż na bazie tego samego materiału wejściowego (czyli zbioru odpowiednich plików *.txt) TypeFriendly jest w stanie wygenerować kilka rodzajów podręczników (różniących się głównie nawigacją pomiędzy poszczególnymi częściami) oraz kilka ich formatów – aktualnie dostępna jest możliwość generowania osobnych rozdziałów w osobnych plikach lub wygenerowanie wszystkiego w jednym duży pliku HTML.
Żeby nie rozpisywać się już zbytnio, o tym co niepotrzebne – skrypt został zaopatrzony w bardzo dobrą dokumentację – wygenerowaną oczywiście w nim samym ;) Z własnego doświadczenia mogę powiedzieć, że jego użytkowanie nie wymaga dużego nakładu pracy, a efekty bardzo szybko się zwracają w postaci uporządkowanych i estetycznych podręczników.
Skrypt i wspomniana dokumentacja jest dostępna do pobrania na stronach grupy Invezzia zajmującej się jego tworzeniem i rozwojem.
Mam nadzieję, że ta lekko chaotyczna prezentacja skryptu zachęciła Was do skorzystania z niego. Jeśli ktoś zakładał tworzenie dokumentacji dla swojego projektu, to przedstawione rozwiązanie ułatwi i przyspieszy ten proces.
