TypeFriendly 0.1.0 wydane

Zyx — śro, 23 lip 2008 10:29:00 +0200

W końcu zakończyliśmy tłumaczenie dokumentacji na język angielski i gotowy od kilkunastu dni kod wreszcie został wydany jako pierwsza wersja systemu generowania dokumentacji TypeFriendly. Można ją pobrać w dziale Pliki na stronie głównej. Dokumentacja dostarczana jest w wersji źródłowej i robi jednocześnie za przykład, dlatego nie obawiajcie się, że czegoś brakuje. Wszystkie informacje potrzebne do zbudowania HTML-owej wersji dokumentacji znajdują się w pliku /info/README.txt - jest to kwestia wklepania jednego polecenia z konsoli. Trwają już prace nad nową stroną Invenzzii i znajdzie się tam miejsce na dokumentację on-line.

O TypeFriendly pisałem dokładniej w poprzednim wpisie i tam znajdziecie więcej informacji. Tutaj dodam tylko, że eXtreme odwalił kawał świetnej roboty, wyczerpująco opisując po polsku całą składnię Markdown z dziesiątkami przykładów. Z pewnością opis ten przyda się wielu osobom.

TypeFriendly

Zyx — śro, 02 lip 2008 20:51:00 +0200

Z eXtremem ciężko pracujemy, by pierwsza wersja ujrzała w końcu światło dzienne i jesteśmy już bardzo blisko. W związku z tym chciałbym bliżej przedstawić ten projekt, który z pewnością powinni docenić inni programiści, autorzy rozmaitych skryptów i poszukujących sensownego narzędzia do generowania dokumentacji. Pomysł na napisanie TypeFriendly zrodził się w mojej głowie po nieudanych zmaganiach z dodaniem paru niezbędnych rzeczy do parsera XSLT dla DocBook. Widać choćby po dokumentacji PHP, co można z tym zrobić (kolorowanie składni, wiele różnych formatów, ogromna ilość pomocnych znaczników), ale nie dajmy się zwariować. To są wręcz tygodnie siedzenia, by osiągnąć podobny efekt. Pomijam już fakt, że byłby on słabo przenośny... wolałem poświęcić te tygodnie na stworzenie czegoś bardziej przydatnego.

TypeFriendly jest więc systemem generowania dokumentacji, ale innego pokroju niż np. phpDocumentor, który skanuje kod źródłowy Twojego projektu i robi opisy do wszystkich napotkanych klas i funkcji. Tutaj rozdziały piszemy sami od A do Z i sami układamy je w żądanym porządku, podobnie jak w DocBooku. Na tym podobieństwa się kończą, ponieważ TF z definicji zawiera już wszystko, co potrzeba, a został tak zaprojektowany, by dokumentację pisało się intuicyjnie.

Cechy:

W TF dokumentację tworzymy, pisząc tekst w zwykłych plikach tekstowych, korzystając ze składni Markdown. Dodatkowo, na początku umieszczamy różne dodatkowe tagi, dzięki którym możemy ustawić tytuł, informacje o wersji czy np. listę "Zobacz także".
TF automatycznie układa nasze pliki w rozdziały na podstawie ich nazwy i sortuje alfabetycznie. Jednak zawsze możemy wprowadzić własny układ - w pliku "ze wskazówkami do sortowania" definiujemy własną kolejność. To, czego tam nie zapisaliśmy, pozostanie alfabetycznie.
TF posiada wbudowaną opcję kolorowania składni kodu źródłowego.
TF samodzielnie generuje pełną nawigację pomiędzy rozdziałami, podobnie jak spis treści.
TF jest zaprojektowany do rozwijania dokumentacji w kilku językach. Posiada nie tylko możliwość przetłumaczenia tekstów interfejsu, ale także proste narzędzie do sprawdzania aktualności "pochodnych wersji językowych".
TF umożliwia wygenerowanie wyjściowej dokumentacji w formacie XHTML (w wersji z wieloma podstronami lub na jednej). Przygotowujemy też specjalny format umożliwiający szybki import dokumentacji do bazy danych i udostępnienie np. możliwości jej komentowania on-line.
TF oprawia dokumentację w bardzo ładną szatę graficzną, którą możecie podziwiać np. w dokumentacji do OPTv2 (robionej właśnie w TF).

Wprawdzie wydania żadnego jeszcze nie było, ale chętni mogą już teraz połączyć się z naszym nowym SVN-em i ściągnąć projekt stamtąd. Link do polecenia checkout jest następujący: http://svn.invenzzia.org/svn/typefriendly/trunk/ - serdecznie zachęcam już teraz do testów. W repozytorium jest plik README oraz będąca już na ukończeniu dokumentacja w języku polskim.

Żeby nie być gołosłownym, pokażę co ciekawsze opcje na przykładzie paru fragmentów. Pierwszym z nich będzie jeden z plików manuala OPTv2 (library.optnode.txt):

Title: Klasa optNode
ShortTitle: optNode
Status: abstract
Extends: library.optcodebuffer
ExtendedBy:
 - library.optscannable
 - library.optcharacterdata
 - library.optexpression

----
Abstrakcyjna klasa węzła. Zapewnia obsługę podstawowych własności, jak rodzic i typ.

Pola klasy
----------
Wszystkie pola klasy są chronione.

 Nazwa         | Typ       | Opis
---------------|-----------|---------------------------------------
 $type         | Integer   | Numeryczny identyfikator typu.
 $parent       | optNode   | Rodzic węzła.

Dostępne identyfikatory typów:

1. `OPT_CDATA_NODE` - `optCharacterData`
2. `OPT_TEXT_NODE` - `optText`
3. `OPT_EXPRESSION_NODE` - `optExpression`
4. `OPT_ELEMENT_NODE` - `optElement`
5. `OPT_ROOT_NODE` - `optRoot`

Na początku pliku znajduje się nagłówek, w którym umieszczamy tzw. tagi. Tam właśnie określany jest właściwy tytuł, a w tym wypadku również zależności między klasami. Zauważmy, że do innych klas odwołujemy się, podając identyfikatory rozdziałów, które je opisują. Oczywiście każdy z tych "obiektowych" tagów posiada także wersję, gdzie nazwy możemy wpisać bezpośrednio (np. gdybyśmy dziedziczyli po klasie wbudowanej w PHP). Dostępnych tagów jest więcej. Przykładowo, można bardzo łatwo zrobić listę "Zobacz także", która wygląda mniej więcej tak:

SeeAlso:
 - chapter.text1
 - chapter.text2
 - chapter.text3

Gdy lista tagów dobiegnie końca, przechodzimy do właściwej treści pisanej w formacie Markdown. Autor zaprojektował go bazując na formatowaniu używanym powszechnie w rozmaitych plikach tekstowych czy e-mailach (można powiedzieć, że napisał parser do składni, która sama wyewoluowała :)). Tekst źródłowy jest przez to niesamowicie czytelny i na dobrą sprawę czyta się go niewiele gorzej, niż gdyby był faktycznie sformatowany. Trochę gorzej, gdy ktoś jest przyzwyczajony już do jakiejś składni wiki, bo MD nie zawsze takowe wiki przypomina (zwróćcie uwagę chociażby na sposób wykonania tabelki). Jednak można się dość łatwo przyzwyczaić - w Markdownie klepiemy również teksty na naszą stronę i muszę powiedzieć, że jest to całkiem przyjemne narzędzie, które z pewnością ujrzycie w niejednym produkcie Invenzzii. Jedyny mankament jest taki, że oficjalny parser obsługuje tylko jeden słuszny format - XHTML. O LaTeXu czy innych na razie trzeba niestety zapomnieć, ale na to już ostrzymy sobie zęby :).

Najgorszy problem przy tworzeniu dokumentacji to nawigacja. Linki "Poprzedni/Następny/W górę" załatwia TypeFriendly, sekcję "Zobacz także" robimy za pomocą znaczników, a co z klikalnymi nazwami funkcji i klas? Myślałem nad tym i wymyśliłem rozwiązanie genialne w swej prostocie. W dodatkowym pliku tekstowym definiujemy kawałki tekstów, które mają zostać zamienione na odnośnik. Przykładowo, wpisujemy tam, że `optClass::parse()` ma, oprócz nadania mu standardowego formatowania, zostać zmienione na odnośnik do library.optclass.parse i już się niczym więcej przejmować nie musimy. Niestety, do takich przeróbek Markdowna jeszcze nie doszliśmy i pierwsza wersja tego bajeru nie będzie jeszcze zawierać. Wszystko w swoim czasie.

TypeFriendly obsługiwany jest w całości z konsoli systemu operacyjnego. Testowaliśmy go na Linuksie i Windowsie - w obu systemach działa póki co bez zarzutów. Do działania potrzebny jest wyłącznie interpreter PHP. W połączeniu z intuicyjną składnią oraz wbudowanym wsparciem dla wielojęzyczności powinno to zachęcić wielu ludzi do pomocy przy tłumaczeniach, rozwoju oryginalnej wersji, a nawet tworzeniu nowych wyjść. Przetworzenie naszych plików na XHTML to kwestia wklepania jednego polecenia:

php ./typefriendly.php -l pl -o xhtml ./sciezka/do/dokumentacji/

Porównajmy to z DocBookiem - sam format jest nieco bardziej rozwlekły, ale stosunkowo łatwy do opanowania. Do konwersji jednak potrzeba trochę więcej narzędzi - DTD, sam zestaw DocBok XSL Stylesheet i wreszcie sam parser XSLT. Jego wybór jest nie bez znaczenia, gdyż ze zwykłym, szybkim i łatwym w użyciu xsltproc nie dostaniemy np. kolorowania składni. Użytkownicy Windowsa natomiast mają kompletnie prze.... jeśli autor projektu dodatkowo zrobi na DocBooku framework do budowania dokumentacji, w którym część narzędzi napisana jest w... Bashu. Nie trzeba takich kwiatków daleko szukać - jak myślicie, co odpowiada za dokumentację PHP? :) Z chęcią bym do niej coś popisał, gdyby choć raz udało mi się uruchomić ichniejszy framework i cokolwiek przetworzyć.

Invenzzia... po polsku - TypeFriendly

TypeFriendly 0.1.0 wydane

TypeFriendly