Jinja24Doc

Dokumentace

Možností bylo několik. Některé však nevyhovovali kuli špatné, nebo obtížné (rozuměj rozsáhlé) škálovatelnosti, jiné postrádali na funkčnosti, například s detekcí parametrů. Po krátké době jsem začal uvažovat o možnosti, si generovat dokumentaci sám. Zejména proto, že je snadné ji získat díky nativní podpoře v jazyku python. Dokumentace však nebyla jediná, nutnou podmínkou bylo získávání argumentů funkcí a metod.

Po rychlém průzkumu modulu pydoc jsem zjistil, že tuto funkčnost nabízí modul inspect. Díky němu je generování dokumentace velmi snadné. Stačilo jen přidat nějaké filtry na názvy entit, nebo jejich původ a výsledek je vidět například na dokumentaci k Poor WSGI.

Malinkou překážkou je pouze dokumentace proměnných. Ta se ale díky modulu inspect udělat dá. Jinja24Doc čte zdrojový soubor modulu, a regulárním výrazem hledá první definici proměnné a zároveň kontroluje předchozí řádek, zda se na něm nevyskytuje komentář. Díky tomu lze psát, sice jednořádkovou, ale alespoň nějakou dokumentaci k proměnným.

Zobrazení

Když už jsem měl data, která chci zobrazit, zbývalo definovat jak je zobrazit. Vhodným krokem, mě tedy přišlo jako správné řešení, použít šablonovací nástroj. Do nedávné doby jsem používal výhradně Teng od Seznamu, ale poslední dobou pokukuji po jiných možnostech. Jeden z nativních systémů pro python je Jinja2. Na rozdíl od systému Mako, nedovoluje tak snadno používat jazyk uvnitř šablony, obdobně, jako to dělá PHP. Proto je u mě Jinja2 zatím v kurzu a je to i zvolený systém pro Jinja24Doc. Od něj také pochází název mého nástroje.

Stačilo už jen šablonám podstrčit nějaké funkce, které by se zevnitř dali volat, a které mi pomohou s tvorbou dokumentace v nějaké hezké podobě. První dvě zásadní metody umí zpracovat pythoní soubor – modul, a vrátí získanou dokumentaci. Druhý umí udělat totéž, ale již zpracovává textový soubor. Z něj umí vytáhnout hlavičky a pak textové informace. Díky tomu, může být část dokumentace uložena přímo v textovém souboru.

Další důležitou funkcí, kterou je možno volat přímo ze šablony, je wiki. Tato funkce, jak už název napovídá, umí formátovat vstupní text. Zde vidím obrovský prostor pro zlepšení. Podobnou funkci sem kdysi psal pro PHP, a ani tam nefunguje úplně skvěle. Začínám mít pocit, že by celé zpracovávání mohlo fungovat jako stavový automat, což se teď děje jen v omezené míře při obarvování v pre blocích.

Nakonec jsem ještě přidal automatické generování odkazů na prvky z modulu. Pokud je tedy v textu nalezeno slovo, které je názvem z předtím zpracované dokumentace, automaticky se na něj vytvoří odkaz. Ten byl následně doplněn titulkem z parametrů dotyčného prvku. Což jsou parametry u funkcí a metod. U tříd jsou to parametry konstruktoru a u proměnných jejich hodnota. Tato funkcionalita není zcela automatická, je třeba zavolat funkci, jejíž vstup je pole vygenerované dokumentace a volitelně stránka, na které se dokumentace nachází. Lze ji však volat jen jednou, a interní stav přepisuje.

Co zbývá

I když je použití nástroje koncipováno tak, že není třeba žádného nastavení, čím více mi leží jeho funkcionalita v hlavě, tím víc vidím, že by přeci jen některé možnosti bylo hezké konfigurovat. Do budoucna ale chci tyto možnosti řešit parametrizováním funkcí. Díky tomu si uživatel sám v šabloně řekne, jak má dokumentace vypadat.

Jeden z konkrétních případů, je právě generování odkazů na známe prvky z dokumentace. Tyto odkazy nefungují zcela správně, a chybí možnost výskytu api ve více souborech.

Problém by někdo mohl vidět i u přístupu ke generování dokumentace. Někdo by chtěl zobrazit i importované funkce a proměnné, jiný ne. A co teprve fakt, že generování každé stránky vyžaduje zpracování všech modulů, na které je možné se z dotyčné stránky odkazovat. Výkonnost mě ale tak moc netrápí. Systém je stavěný na off-line generování dokumentace, a to přeci jen nemusí být hned.

Aktuálně nástroj testuji právě při generování dokumentace ke všem pod-projektům bývalého PoorHttp, který se rozpadl na tři jednotlivé části. Po otestování a případném opravení zásadních nedostatků, vygeneruji zdrojový tarball ke stažení, a dojde i na registraci do PyPI. Kdyby snad někdo chtěl pomoci, rád přijmu jeho návrhy, připomínky, opravy a to jak kódu, tak celkového řešení, nebo i dokumentace. Která, protože je v angličtině, zdaleka není napsaná tak, jak by asi měla být.

Projekt žije v git repositáři na SourceForge.Net a zde má i své diskuzní fórum a bug-reportovací systém.