Jog Jajcusia

Czyszczenie PyXMPP

14 września 2004 22:19:42 | kategorie: programowanie, python, pyxmpp,

Najwyraźniej jest jakieś zainteresowanie moją pythonową biblioteką XMPP. Ludzie (przynajmniej paru) chcą tego używać, ale wielu od razu się zniechęca brakiem dokumentacji, inni po próbach zrozumienia o co w tym biega. Nie dziwię się -- kod zamotany jak rzadko, a dokumentacji praktycznie brak. Bardziej dziwię się ludziom takim jak pete, czy Zgoda, którzy tego używają i nawet mnie z tego powodu nie męczą. Jednak uznałem, że trzeba coś z tym zrobić...

Więc od paru dni zamiast dodawać nowe ficzery do CJC, poprawiać w nim bugi, czy implementacje protokołów w PyXMPP to ślęczę nad kodem PyXMPP i, terroryzowany przez pylinta czyszczę kod, co jakiś czas robiąc: cvs commit -m "cleaning up...". Przy jakiś czas coś psuję głupimi literówkami, albo zamierzonymi zmianami w API PyXMPP (sorry developerzy), np. zamiana nazwy parametru konstruktora klasy Stanza z type na typ, bo ta pierwsza nazwa zakrywała nazwę wbudowanej funkcji. Jak już wspominałem większość marudzenia pylinta dotyczy braku docstringów, a więc je dodawałem na bieżąco. Oczywiście nie "", ale w miarę konkretną dokumentację, która się może jakiemuś developerowi przydać. I tu wkracza Epydoc...

Normalnie do przetwarzania dokumentacji w pythonie służy narzędzie pydoc. Jednak jest ono głupie, bo traktuje docstringi jako czysty tekst, bez formatowania czy hyperlinków. Taka dokumentacja jest mało czytelna i niewygodna. Już jakiś czas temu szukałem informacji na temat robienia porządnej dokumentacji do kodu Pythona i dowiedziałem się, że the right way to jest (lub raczej będzie) używanie w docstringsch reStructuredText. Narzędzi do przetwarzania tego wtedy nie znalazłem (słabo szukałem, albo jeszcze nie było), znalazłem tylko docutils które, między innymi, takim narzędziem mają się stać, ale na razie umieją tylko parsować reStructuredText i konwertować to do mądrzejszych formatów. Mimo braku narzędzia do obróbki tego jednak już wtedy postanowiłem reStructuredText używać. I nawet użyłem w tych skrawkach dokumentacji które zdążyłem zrobić.

Teraz przy czyszczeniu kodu znowu szukałem narzędzia do generowania dokumentacji z kodu. Tym razem znalazłem. Docutils wciąż nie umieją wyciągać dokumentacji z kodu Pythona, ale mogą być wykorzystane przez Epydoca, który to potrafi. Ma on niby swój markup dla docstringów, ale potrafi, przy pomocy docutils obsłużyć także reStructuredText (ale tylko tworząc dokumentację w HTML). Więc to właśnie podpiąłem pod doc/Makefile. Okazało się, że stare kawałki dokumentacji musiałem popoprawiać, żeby Epydoc sobie z tym poradził. Nowe tworzyłem od razu pod tandem Epydoc+docutils. I nawet są jakieś efekty. Otrzymana dokumentacja wygląda nieźle, jest dość przejrzysta... tylko ma olbrzymie braki. :-( Kiedy ja to wszystko opiszę?