Jinja24Doc - dokumentační nástroj pro Python

O víkendu byla na pypi publikována první release verze dokumentačního nástroje Jinja24Doc pro python. Nyní je tak dostupný i přes pip install jinja24doc. Více na homepage projektu. Připomínky, náměty i hlášení chyb je vítáno. Ideálně přes SF Discussion nebo SF Tickets.

27.1.2014 10:28 | McBig | Zajímavý software

Komentáře

[little.owl]

Zajimave. (a) Jakou to ma vyhodu oproti Sphinx? (b) Umi si to poradit s reStructuredText?

[McBig]

Proti Sphinx je to jednoduché. Cíl je nulová konfigurace a vygenerování nápovědy do 60 sekund. To teď sice jde, ale není moc hezká. Ještě mám v plánu nějaké šablony. Sphinxu jsem nevěnoval mnoho času, ale pořádně jsem nevěděl co mám udělat abych ovládl výsledek, přišlo mi to komplikované.

Jinja24Doc má být malá a rychle použitelná. Původně to měla být jen náhrada za pydoc, ale postupně toho umí přeci jen víc.

Jinak reStructuredText Jinja24Doc zmáknutý na 100% určitě nemá, chystám se na nějaké testy abych zjistil co všechno to neumí. Ale cíl je aby pokud to bude dávat smysl byl reStructuredText kompletně podporován.

[Josef Kufner]

Cíl a motivace by měly být první dva odstavce na webu projektu.

Má to oproti Sphinxu nějakou přidanou hodnotu nebo je to jen obvyklé NIH? Nebylo by lepší šťouchnout do vývojářů Sphinxu, ať udělají lepší výchozí konfiguraci?

[McBig]

No důležitější mi přišlo spíš ukázat, jak rychle a snadno se daná věc dá použít. Motivace tam je taky, ale pravda, schovaná, je to ten odstavec o pár slovech na závěr, ani nevím jestli se to takhle píše správně, snad ano, maximálně mě někdo opraví, kéž by to byl rodilý mluvčí ...

Porovnat se Sphixem to bohužel nedokážu. Právě proto, že neznám všechny jeho možnosti. Co se výstupu týče, ano nemá to vyhledávání, generuje to statické stránky a něco jako vyhledávání (alespoň na úrovni javascriptu) by šlo určitě dodělat.

Než jsem to napsal, hledal sem něco tak lehkého jako pydoc, akorát jsem si chtěl ladit styl, resp. vzhled výsledku. Nechtěl sem prostě něco konfigurovat, Sphinx mě připomíná doxygen, to jsem nechtěl.

[Josef Kufner]

Proč bych ale měl něco používat, když nevím, k čemu to je? Ještě před návodem prostě chybí kapitola "What is Jinja24Doc?". Žádné dlouhé kecy, jeden či dva odstavce pro člověka, který ten projekt vidí poprvé, aby se mohl rozhodnout, zda to je to, co hledá.

Ono to tam tak trochu máš, ale je to schované. Tyhle věci musí mít svůj vlastní nadpis a musí být nad okrajem první obrazovky (tedy než je potřeba scrollovat), aby se to snadno našlo na první pohled. Teď když tu stránku otevřu, vidím návod a nevidím k čemu je.

U samotného návodu se hodí použít číslování (<ol>), aby se v tom lépe orientovalo. Pokud je bodů málo (2-3), zdůrazníš tím jednoduchost použití.

[little.owl]

Tak to tam napiste; ja spokojene pouzivam Sphinx i pydoc a tady jsem opravdu nevedel, proc bych to mel vubec zkusit pouzit .

[McBig]

Děkuji všem za feedback. Pomohlo mi to víc než se může zdát. Dokumentaci jsem trochu doplnil a opravil.

A sám sem si uvědomil, co jsem z toho vlastně chtěl mít. Nikdy nemělo jít o konkurenci Sphinxu, ale právě o jakýsi lepší pydoc. Tento cíl myslím splněn byl. Ještě plánuji napsat pár "hezkých" šablon, možná zkusím i js vyhledávání, ale to nikdy nebylo cílem.

Konec konců, je také dost pravděpodobné že zůstanu jediným uživatelem :) Je to pro mě ale cenná zkušenost, zkusit propagovat vlastní práci. Tím spíš, že toto není jediný nástroj svého druhu, první a ani poslední. Než jsem se do něj pustil, strávil jsem nějaký čas prozkoumávání terénu. Ne proto, abych věděl jak to mám napsat, ale zda to vůbec musím psát. Cíl bylo použít něco jiného :)

[little.owl]

Tak jsem se na to opet kouknul, obsahove lepsi, ale ta English by opravdu potrebovala korekci. Pritom vase anglictina neni spatna a paradoxne delate chyby v zakladnich vecech.

Pro zacatek se kouknete na uziti clenu - zakladni pravidla, 's' ve tretich osobach s ohledem na podmet - doslova si dejte do paru sloveso-podmet a na standardni slovosled.