Wpis ten poświęcę „amatorskiej poligrafii” internetowej. Zapewne wielu czytelników tego bloga marzyło wprost by zasadzić drzewo, spłodzić syna (mam dwóch!! ale nie dam – sami sobie zróbcie), no i oczywiście napisać książkę. Pomysłów genialnych nam nie brak, a jeśli brak, to przecież nadal można próbować dowodzić Wielkiego Twierdzenia Fermata – fakt że zostało dowiedzione nijak przecież nie wpływa na atrakcyjność i poczytność błędnych dowodów! Zatem – pisać mamy co. W tym wpisie przedstawię ciekawą metodę – jak pisać z pewną przyjemnością.

    Onegdaj pisałem że korzystając z cudzego skryptu w Pythonie mozna osiągać wyniki jak Terrence Tao ( przynajmniej w warstwie graficznej). Tym razem podam inny przepis. Jest on znacznie bardziej złożony, ale ma zalety. Po pierwsze może się przydać początkującym programistom, zwłaszcza młodym Pythonom. Po drugie harmonizuje z moim ulubionym systemem matematyki symbolicznej – Sage, który wszystkim rekomenduję przy każdej nadarzającej się okazji. Po trzecie pozwala w miarę bezbolesny sposób generować bardzo dużą liczbę formatów plików, co jest w dzisiejszych czasach wielką zaletą, i co sprawia, ze może sie przydać w pracy także administratorom systemów…

    Przedstawimy zagadnienie w punktach. Przepis jest taki ( oczywiście świadomy użytkownik może dokonać zmian w przepisie, wręcz zachęcam do tego, ale jak mu wyjdzie zakalec – proszę mieć pretensję do siebie):

  1. Instalujemy system zarządzania/generowania dokumentacji dla Pyhtona, Sphinx W Ubuntu to jest  jak zwykle krótka piłka – wszystko jest w repozytoriach. 
  2. Zgodnie z instrukcją tworzymy projekt dokumentacji wydając w dogodnym katalogu polecenie $sphinx-quickstart. Wykonanie polecenia wiąże się z odpowiedzią na kilkanaście pytań – większość odpowiedzi domyślnych jest dobra, należy zwrócić uwagę na dwie sprawy. Po pierwsze twórcy dokumentacji sugerują: „Be sure to say yes to the “autodoc” extension.” a my ze zrozumieniem stosujemy sie do tej wskazówki. Po drugie, jeśli chcemy – a chcemy i to bardzo – produkować ładne wzory matematyczne w plikach html – musimy użyć jsMath. temat ten poruszymy w punkcie kolejnym.
  3. wykonanie polecenia $sphinx-quickstart tworzy na dysku strukturę katalogów oraz pliki konfiguracyjne. jednym z nich jest conf.py. Zapamiętajmy ta nazwę. Innym jest Makefile. Powstaje także plik index.rst ( lub index.txt jeśli tak ustaliliśmy odpowiadając na pytanie podczas pracy skryptu)
  4. renderowanie wzorów w plikach html będzie robione przez jsMath. Ściągamy zatem zipa z kodem i rozpakowujemy gdzieś na boku. W katalogu z naszym projektem publikacji, po użyciu polecenia $sphinx-quickstart pojawiła sie struktura katalogów, a wśród nich jeden o nazwie _static. Kopiujemy do niego rozpakowany jsMath. Każda publikacja którą chcemy opublikować wg. tego przepisu w internecie, musi mieć jsMath w katalogu _static. Teraz musimy powiedzieć Sphinxowi gdzie jest jsMath i robimy to dodając na końcu pliku conf.py linię: jsmath_path=’jsMath-3.6e/easy/load.js’ Oczywiście ścieżka ta zależy od wersji jsMath którą pobraliśmy z neta. Jest to ścieżka względna ( nie zaczyna sie od „/” ) co wskazuje na wnętrze katalog _static. 
  5. Jeśli nie będziemy publikowali w necie, ale gdzieś na własnym serwerze, jsMath może znajdować się w innym miejscu, a zmienna jsmath_path powinna wskazywać na stosowny katalog w sposób bezwzględny.
  6. W katalogu projektu na naszym dysku twardym dokonujemy uwiecznienia naszych myśli za pomocą edytora własnego wyboru, na przykład vi. Składnia markupa do Sphinxa jest bardzo prosta, dostosowana do weba, zaś składanie wzorów jest kompatybilne z LaTeX, poza drobnymi szczegółami. Wzory „inline” wyglądają tak: :math:’-wzór-w-LaTeX’, wzory w nowych liniach taguje sie w nieco bardziej złożony sposób, ale składnia wzoru jest nadal LaTeX-owa. Odsyłam do dokumentacji. Zwrócę uwagę, że chociaż w podlinkowanej instrukcji piszą o mathjax, składnia Sphinksa sie nie zmienia. Zmienia się tylko narzędzie do renderowania.
  7. Skoro mamy gotowy plik z treścią ( a ja dla testu bezwstydnie skopiowałem fragment tekstu stąd – pod linkiem source jest źródło całej książki o „fizyce teoretycznej” z olbrzymią ilością wzorów, w tym równaniami Clerka-Maxwella), możemy dokonać testowej, lokalnej kompilacji. W tym celu w katalogu z plikiem conf.py i Makefile wydajemy polecenie make latex, następnie make html, a jak ktoś che to make epub, make latexpdf, make man i kilkanaście innych.
  8. W wyniku w katalogu _build powinny pojawiać sie katalogi latex, html itp. a w nich pliki latexa czy html-a. Plik latexa można edytować, lub skompilować latexem by uzyskać pdf-a. Proszę pooglądać co dostajemy w wyniku. Zaznaczam także że nie wszystkimi błędami należy sie zrażać, w razie problemów należy sprawdzić ścieżki do jsMath, a podczas kompilacji LaTeX za pomocą linii komend, polecenie R(un) pozwala zignorować mniej krytyczne błędy. 
  9. Jeśli w punkcie 9-tym udało Wam sie uzyskać poprawny plik html/latex – gratulacje – jesteście gotowi do dalszych kroków w celu publikacji własnego dzieła. W jubileuszowym punkcie 10 podsumujemy co uzyskaliśmy.
  10. Mamy system Sphinx który renderuje dla nas piki latex, epub czy html zawierające nasze rewolucyjne przemyślenia. System ten może zostać użyty do generowania dokumentacji kodu źródłowego – takie jest jego oryginalne zastosowanie – ale także do tworzenia dokumentacji, publikacji, książek, artykułów, prezentacji. Pisanie odbywa się ulubionym narzędziem, a formatowanie wzorów odbywa sie za pomocą składni LaTeX. Generowane strony  html mogą zawierać wzory renderowane przez jsMath, o czym wspomniałem, jsMath zostanie „podlinkowany” z katalogi _static. Jako alternatywę, o czym nie wspomniałem, można użyć generowania wzorów jako  obrazki .png, które to rozwiązanie jest średnio wygodne, ale czasami przydatne.

    Na tym etapie mamy zatem w pełni funkcjonalne środowisko do zaawansowanej publikacji dokumentacji i tekstów matematycznych w rozmaitych formatach. Środowisko to jest warte uwagi zwłaszcza dlatego, że system Sage Math używa właśnie Sphinxa do generowania dokumentacji, a w istocie każdy kto używa Sage Math – znajdzie Shinxa zintegrowanego w jego wnętrzu. Co więcej – jeśli kto ma ochotę – może wszystko co tu opisano ominąć i tworząc w katalogach Sage własne pliko może wymusić ich „kompilację” powiedzmy do html-a poleceniem sage –docbuild html. Tym sposobem nie uzyskujemy jednak 100% kontroli wyniku, pracujemy po prostu w tym co programiści Sage dla nas przygotowali – a przygotowali na przykład domyślny css. Ponadto metoda ta nie nadaje się za dobrze do produkcji dokumentacji „ogólnego przeznaczenia” do projektów programistycznych czy dla administratorów systemów.

    Przejdźmy teraz do zagadnienia publikacji w necie. Publikacja w necie wymaga zrealizowania jednej z 2 alternatyw. Albo kupimy sobie serwer www, i w wygodny dla nas sposób wstawimy weń kody html, udostępniając je ludzkości, albo uzyjemy serwisu ReadTheDocs. Serwis jest malutki, darmowy i bardzo ciekawy. Pobiera on dokumentację w formacie Sphinx z repozytorium kodu, jak svn, Mercurial, Git itp. buduje dokumentację poleceniami make – podobnie jak my na swoim dysku – a wynik udostępnia szerokiej publiczności. Być może takich serwisów jest więcej – ja znalazłem ten. Aby go użyć idziemy na łatwiznę ( chyba że mamy już własne repozytorium kodu w necie – wtedy może być jeszcze łatwiej) Ne jestem programistą, pewnie ktoś może tu zaproponować bardziej sensowną drogę, na przykład kod w Python można trzymać w PyPi. Czy oni budują i hostują dokumentację – nie wiem, ale pewnie powinni – w końcu Sphinx to natywne narzędzie Pythona. Ja posłużyłem sie, byc może nieco na około, wspomnianym serwisem Read The Docs, oraz Gągle Code. Aby i Wam ta sztuka się udała postępujcie tak:

  1. Zakładamy konto w code.google.com W miejscu tym będziemy przechowywać kod źródłowy naszej publikacji. Tworzymy podczas rejestracji projekt i nazywamy go stosownie szumnie do jego znaczenia dla ludzkości. Zamiast gągle można użyć dowolnego repozytorium Git, Mercurial, SVN, co tam kto woli. Można mieć własny serwer. Jeśli ktoś będzie produkował dokumentację w pracy – krok ten nie jest potrzebny. Ale my tu mówimy o publikowaniu dla milionów a nie o zabawie w piaskownicy.
  2. Instalujemy na swoim ulubionym systemie czyli linuxie, system zarządzania kodem, ja użyłem Mercurial i na tym sie skupię w tym opisie. Pod Ubuntu – z repozytoriów.
  3. Tworzymy clona projektu google, za pomocą instrukcji opisanej tu. Do katalogu projektu sklonowanego z gągla kopiujemy całą zawartość katalogu z naszą publikacją. Dbamy szczególnie o to by obok plików z katalogu głównego – w którym są index.rst, rozdziały naszej publikacji oraz conf.py i Makefile, przeniósł sie katalog _static wraz z zawartością.
  4. W wyniku wykonania hg push dostajemy przeniesienie kodu do repozytorium gagle.
  5. zakładamy konto w serwisie ReadTheDocs, a następnie importujemy z gągla nasz kod. System automatycznie i samodzielnie dokona kompilacji dokumentacji i po dłuższej lub krótszej chwili udostępni nam ją do pobrania. Można pobrać plik pdf czy epub, dla mnie jednak najbardziej interesująca jest opcja html. A wynik dla mojego testu wygląda tak. No mam nadzieję że Państwo to widzą! Jak dla mnie – całkiem fajnie – a fakt że kod siedzi u mnie na dysku – bardzo podnosi wartość tej metody.

    Czy warto tyle pracy poświęcić by uzyskać taki efekt? Ocenę zostawiam Wam. Mnie sie Sphinx podoba. W razie stosowania opcji pisania w strukturach katalogów Sage ma sie dostęp do kodu Sage i możliwości generowania na przykład wykresów. W ramach tworzenia dokumentacji w pythonie dostępne sa całkiem potężne możliwości bibliotek sympy ( obliczenia symboliczne w python) czy mathplot. Wydaje sie że to całkiem nieźle się zapowiada…

    Od dawna marzy mi sie koncepcję matematycznej książki interaktywnej. Piszemy własną wersję dowodu Epokowego Twierdzenia – a użytkownik dostaje w wyniku nie tylko treść, ale i interaktywne kawałki kodu które pozwalają obraca obrazki 3D, rysować funkcje czy wyliczać własne rozwiązania równań. Autor piszą książkę nie wykonuje już wyliczania wyznacznika na kartce, czy w Maple – w kodzie książki pisze det(M) – a podczas generowania publikacji wartość ta zostaje wyliczona. Fajnie by było… Wydaje mi sie że jeszcze trzeba będzie poczekać na takie cuda, chociaż Sage jest już prawie, prawie takim narzędziem.Brakuje kilku rzeczy – a jedną z nich jest – hosting – czyli dostęp do serwerów w internecie które pozwalają na publikację własnej treści ( jak na blogu) ale zarazem interpretują zagnieżdżony kod Sage. Może kiedyś…