Dziś jest czwartek, 20 listopada 2008 roku (z kalendarza...)

TypeFriendly

Icon

01.08.2008, 12:37

Projekty

Komentarze (8)

Powrót

Kilka dni temu w Internecie ukazała się pierwsza wersja skryptu TypeFriendly służącego do generowania dokumentacji. Napisałem ją, zniechęcony efektami pracy w DocBooku. W przeciwieństwie do narzędzi typu phpDocumentor, wszystkie rozdziały pisze się tutaj (jeszcze) ręcznie, natomiast skrypt dba o ich poprawne przetworzenie na XHTML, utworzenie nawigacji itd. Natomiast dzisiaj na Zyxist.com pojawił się samouczek pokazujący, jak rozpocząć pracę nad własną dokumentacją w tym systemie.

TypeFriendly oparty jest na opisywanej niedawno tutaj składni Markdown cechującej się wyjątkową czytelnością kodu źródłowego i możliwościami. Poczynione w nim zostały małe zmiany wizualne mające dostosować go do potrzeb projektu, ale myślę, że nie powinno być problemów z przyzwyczajeniem. System wspiera kolorowanie składni przykładów, prace nad dokumentacjami wielojęzycznymi oraz opisami API projektu. Napisany jest w PHP5 i obsługiwany jest w całości z wiersza poleceń systemu operacyjnego.

Z projektu jestem zadowolony, ale nie oznacza to końca jego rozwoju. Wciąż pozostało dużo do zrobienia i do dodania, a jednym z priorytetów jest dodanie obsługi innych formatów wyjściowych, niż XHTML (problem wynika z tego, że używany w projekcie parser Markdowna nie potrafi wygenerować niczego innego). Ponadto mam zamiar napisać system automatycznego generowania plików na podstawie kodu źródłowego, jak to robi phpDocumentor.

Za wydanie odpowiada Invenzzia i stamtąd też można ściągnąć całość. Do archiwum dołączona jest polska oraz angielska dokumentacja w wersjach źródłowych, które robią jednocześnie za przykład użycia. Więcej informacji znajdziecie w przypisach oraz na devblogu Invenzzii.

Powrót

Komentarze

Napisał takieGadanie w piątek, 1 sierpnia 2008 o 14:29

To ja poproszę obsługę generowania WordaML albo ODF ;P
PS. Zapowiada się nieźle

Napisał Albi w piątek, 1 sierpnia 2008 o 14:31

Czyli rozumiem że teraz znajdzie się czas na OPT i OPF? :>

Napisał Elf w piątek, 1 sierpnia 2008 o 16:46

A może by tak dopisać dodatkowy output format do phpDocumentatora zamiast wynajdywać koło? Może przy okazji wyszłoby jak się sprawdza ten Markdown i samo TypeFriendly.

Napisał Zyx w piątek, 1 sierpnia 2008 o 18:59

Jakie wynajdywanie koła na nowo? Dokumentacja dokumentacji nierówna - popatrz sobie dokładnie, co generuje jeden skrypt, a co drugi. phpDocumentor może i świetnie radzi sobie z opisami API, ale do innych tekstów jest beznadziejny (zresztą, nie po to rzucałem DocBooka, by do niego wrócić). Wiem, co mówię, bo używałem tego skryptu, a nawet artykuł o nim napisałem. Co byś wybrał do pisania np. podręcznika użytkownika (a nie programisty)? Ponadto phpDocumentor nie wygeneruje Ci dokumentacji do projektu C++, a TypeFriendly i owszem :).

Albi -> a popatrz sobie z łaski swojej na SVN. O ile dobrze pamiętam, prawie cały lipiec siedziałem nad kodem OPTv2 :)

Napisał DeyV w sobotę, 2 sierpnia 2008 o 17:58

Długo trzeba było czekać na wydanie tego projektu, ale wygląda na to, że było warto. Co prawda na razie tylko pobieżnie przejrzałem dokumentację i nie wiem jeszcze, jak będzie się na tym pracować "w praktyce" ale już teraz jestem zachwycony.
Zrobiliście kawał dobrej roboty, i jeśli nadal będziecie ten projekt rozwijać, to szybko może się stać najwartościowszym narzędziem z tych, które dotychczas udało Wam się wypuścić!

Napisał Zyx w sobotę, 2 sierpnia 2008 o 20:30

W połowie sierpnia powinno być wydanie 0.1.1 z paroma poprawkami itd. - część z nich miała być już w tej wersji, ale się nie zrozumieliśmy z eXtremem co do terminu ich skończenia. Dzięki za uwagi, na razie spadam na zasłużony urlop, co oznacza, że przez najbliższy tydzień nie będzie Wam miał kto aktywować komentarzy :).

Napisał Elf w wtorek, 12 sierpnia 2008 o 12:27

W artykule http://artykuly.zyxist.com/czytaj.php/dokumentacje_w_typefriendly masz akapit o dokumentacji API. To generuje się z kodu. Chyba łatwiej napisać output dla phpDocumentora (czy Doxygen) tworzący dokumentacje w składni Markdown, niż pisać nowy generator.

Napisał Zyx w wtorek, 12 sierpnia 2008 o 14:32

Tja... zapomniałem o Doxygen :). Kurde, w sumie racja, przecież to obsługuje już trochę języków, a tylko tego głównie trzeba. TypeFriendly, choć napisany jest w PHP, może być stosowany do wielu innych rzeczy, nawet niezwiązanych zupełnie z programowaniem.

Strona 1 z 1 :: 1

Skomentuj

NickInformacja
E-mailTylko do użytku wewnętrznego.
WWWNie zapomnij o http://
LayoutNapisz tu, czy widzisz dzienny czy nocny layout.
WpisFormatowanie wiki
Internauto, pamiętaj! Wolność to nie samowola - dbaj o kulturę wypowiedzi oraz dyskusji w sieci.

Na Zyxist.com panuje swoboda wyrażania opinii oraz krytyki pod dowolnym adresem. Jedyny warunek: musi być ona kulturalna i rzeczowa. Na chamstwo, prostactwo lub jawne obrażanie kogokolwiek nie ma tu miejsca i takie komentarze są bardzo szybko usuwane. Jeśli zamierzasz polemizować z treścią wpisu, wpierw uważnie ją przeczytaj.

© Tomasz "Zyx" Jędrzejewski 2005 - 2008 | Wykonanych zapytań: 2 | Serwer wirtualny zapewnia