Dokumentacja dla wersji 3-dev i instalacja Sphinxa

Wraz z rozpoczęciem prac nad nową wersją frameworka, która będzie oznaczona numerem 3, zapowiedziano, że zmianie ulegnie również dokumentacja. Już teraz odwiedzając repozytorium na githubie można zobaczyć jak to wszystko będzie wyglądało. Dokumentacja została oparta na silniku Sphinx, co sprawia, że w łatwy sposób możemy wygenerować dokumentację w różnym formacie np. HTML, PDF itp.

Kolejnym plusem jest samo pisanie dokumentacji – nie musimy już “babrać się” w HTMLu, ponieważ mamy do tego specjalne znaczniki (reStructuredText), które znacznie usprawniają pracę. Nową dokumentację można już przeglądać online, chociaż różnie wyglądało do tej pory z jej aktualnością (na szczęście ostatnio nastąpiły w tej kwestii zmiany na plus – co zawsze można sprawdzić spoglądając na stopkę strony).

Oczywiście jest jeden minus. Aby mieć dostęp do najnowszej wersji dokumentacji w wersji offline, trzeba ją sobie na chwilę obecną samodzielnie wygenerować (i tak już raczej zostanie). Aby bezboleśnie przeprowadzić Was przez ten proces, przygotowałem małą instrukcję, którą sam z powodzeniem zastosowałem (Windows 7).

Ponieważ Sphinx oparty jest na Pythonie, dlatego pierwszym krokiem będzie właśnie instalacja samego Pythona (o ile jeszcze nie mamy go na swoim komputerze). Tak więc udajemy się do działu download i po ściągnięciu (w moim przypadku instalator windows dla wersji 2.7.3) dokonujemy instalacji Pythona.

Naszym następnym krokiem jest pobranie i instalacja pakietu setuptools. Tutaj należy dokonać wyboru zależnie od wybranej wcześniej wersji Pythona (w moim przypadku instalator windows dla wersji 2.7). Jeśli instalacja przebiegła prawidłowo, wchodzimy w wiersz poleceń Windows (cmd) i tam zaczynamy instalację Sphinxa, wykonując kolejno polecenia:

easy_install sphinx=1.2.3
easy_install sphinxcontrib-phpdomain

Tutaj mały tip. Jeśli polecenie easy_install nie jest rozpoznawane, należy dodać katalog, w którym zainstalowaliśmy Pythona do zmiennych środowiskowych. W tym celu wybieramy zmienną Path i dodajemy na końcu wspomniany katalog (w moim przypadku było to: C:\Python27;).

Zmienne środowiskowe (Windows 7)

Po zainstalowaniu Sphinxa musimy doinstalować jeszcze rozszerzenie, które jest odpowiedzialne za formatowanie bloków z kodem w dokumentacji. W tym celu z poziomu linii komend wchodzimy do katalogu twój_codeigniter/user_guide_src/cilexer i wykonujemy polecenie:

setyp.py install

Teraz pozostaje nam już tylko wygenerowanie naszej dokumentacji. W tym celu będąc w katalogu twój_codeigniter/user_guide_src wykonujemy polecenie:

sphinx-build -b html source doc

gdzie source, to katalog z którego generowana będzie dokumentacja, a doc to katalog do którego dokumentacja zostanie wygenerowana. No i to by było na tyle – możemy się teraz cieszyć najnowszą wersją dokumentacji dla wersji dev CodeIgnitera 3 :)

Dodaj komentarz

This site uses Akismet to reduce spam. Learn how your comment data is processed.