Generování statického webu

V posledních dnech se zabývám tvorbou ucelených stránek pro projekt Poor Http for Python. Stránky jako takové budou celkem prosté, budou na nich základní informace o projektu ve dvou jazycích, odkazy, archívy ke stažení a dokumentace v podobě referenční příručky a pár příkladů (tutoriál).

Vzhledem k tomu, že stránky budou statického charakteru, je zbytečné aby byly dynamické, tedy aby je server nějakým způsobem skládal. Jediná výhoda by v tomto směru byla jen snadná údržba stránek a především snadná tvorba, neboť stránky obsahují mnoho společného kódu. Tímto kódem je například hlavička, menu, odkazy na fóra a patička. K takovému skládání html se vysloveně hodí rozšíření SSI http serveru. Provoz stránek bude zajištěn vlastním serverem, a tak podpora SSI na straně serveru, je téměř to poslední, co by mě trápilo.

Problém nastal s Lighttpd. Ten sice SSI podporuje, alespoň v tom základním režimu, nicméně z neznámých důvodů stránky občas odmítne zpracovat, do logu nevypíše žádnou chybovou hlášku a vrátí zdrojový kód. Po několika hodinách pokusů, testů a četby různých diskuzních fór sem tuto možnost prostě vzdal. K lepení, i když ne jen k němu se ale stejně tak dobře dá použít šablonovací nástroj Teng z laboratoří českého Seznam.cz.

Napsal sem si proto velmi jednoduchý program tgen.py, který zpracuje dostupné šablony a vygeneruje z nich statický web. Díky tomu, budu moci snadno stránky ne jen tvořit, ale i upravovat a jedním příkazem pak dostanu aktuální statickou podobu. Jednoduchý kód v pythonu by šel různě ohýbat například tak, že dostane šablonu jako parametr, snadno by se pak dal vytvořit Makefile na vygenerování stránek skrze závislosti. Ovšem celé generování proběhne tak rychle, že je to zbytečné.

I když je rozhraní Poor Http velmi podobné mod_pythonu, jisté odchylky se rozhodně má. Navíc je možné, že případný uživatel Poor Http serveru mod_python nezná. Tak jako tak, musel by obtížně zkoušet zda je chování stejné metodou pokus omyl, nebo studovat kód. Snažil sem se tedy celý kód náležitě zdokumentovat. Hned od prvního řádku komentáře sem uvažoval, že dokumentaci vygeneruji nějakým vhodným nástrojem. Jelikož projekt obsahuje i nadstavbu nad modulem mod_python a ten je závislý na Apache serveru, je generování dokumentace prostřednictvím nástroje pydoc krapet komplikované, a navíc není tak hezké.

Mám sice zkušenosti s nástrojem Natural Docs, ovšem ten je nyní velmi zastaralý a není tak automatický jako Doxygen. Proto padla volba na Doxygen a jeho pomocník doxypy. Ten umí zpracovat nativní pythoní komentáře tak, aby je použil i Doxygen. Výsledkem je pak dokumentace generovaná z kódu a komentářů jak v běžném pythonvském režimu, tak referenční příručka v html generovaná s Doxygenem. Mimochodem pydoc umí také generovat html ;)

Když už sem byl u té dokumentace, dalším logickým krokem byl nějaký příklad použití, instalace, konfigurace a hello world aplikace. I k tomu se dá Doxygen použít, ale jak sem časem zjistil, je to trochu těžkopádné. Rád sem si proto vzpomněl na praktiky jednoho mého bývalého zaměstnavatele, který dokumentaci nechal psát v DocBooku a dál z ní generoval požadovaný formát. Po pár testech sem se pustil i touto cestou. Výsledná dokumentace bude psaná formou knihy a minimálně bude obsahovat kapitoly věnované instalaci, konfiguraci a ukázky použití. Ovšem prezentovat dokumentaci ve formátu xml není to pravé ořechové a tak sem začal hledat mechanismy generování jiných formátů, především html a pdf.

Nejpříjemnějším nástrojem se pro mě stal xsltproc. Je rychlý, psaný v čistém C a pracuje dobře. Pár ukázek stačilo pro vygenerování požadované podoby stránek pomocí nadefinovaného stylu. Ovšem velmi brzo sem narazil na rozšíření, které obarvuje ukázkový kód. Barevná, resp. zvýrazněná syntax je pro takovou dokumentaci rozhodně vítaným zpestřením. Ovšem to už xsltproc nezvládne a tak se má pozornost musela s velkým smutkem obrátit na jiné generátory psané v jazyku Java. Nakonec generuji html pomocí Saxonu. Je to sice zdlouhavé, trvá to asi 10x tak dlouho, ale na druhou stranu, budu to provádět jen jednou za čas při aktualizaci a ten obarvený kód za to stojí.

S pdf je to trochu obtížnější, tato cesta mě ještě čeká, protože standardně nelze generovat s českými fonty. Rozhodl sem se tedy dát přednost dokončení dokumentace s tím, že pro začátek bude stačit html verze. Rozhodně jde ale o velmi zajímavou disciplínu, při které sem z různých zdrojů zjistil, že pomocí nástrojů jako je Saxon nebo xsltproc lze stejně snadno generovat i klasický web.

Tento text budiž tedy vodítkem těm, které takové lapálie ještě čekají. Web lze generovat mnoha způsoby a dokumentace taktéž. V tomto směru sem myslím rozhodně zvolil správný přístup v případě referenční příručky, kdy je dokumentace „dostupná” hned dvěma způsoby. Je ale docela možné, že její část ještě přesunu do dokumentační knihy.

Díky novému přístupu k tvorbě webu, sem se rozhodl pro off-line generování i jiných stránek, a k běžným elektronickým vizitkám se postavím velmi nekompromisně. Sice přijdu o on-line editaci, ale i ta by se dala provést v podobě rozběhnutí generátoru tgen.py na straně serveru a editace šablon pomocí net2ftp či jiného webového ftp rozhraní.