Dotaz: Psaní dokumentace pro webovou aplikaci

[Josef Kufner]

Dobré ráno,

přemýšlím, v čem psát dokumentaci k složitější webové aplikaci napsané v PHP. Chci, aby bylo možné vyrobit tisknutelné PDF (pomocí LaTeXu), a aby bylo možné vložit dokumentaci přímo do aplikace (HTML).

Dokumentace bude tvořena statickým textem. Není to o generování referenční příručky ze zdrojáků, ale o popisu, jak a proč je co uděláno, jak se jednotlivé komponenty dají dál používat a podobně. Druhou takovou "knihou" pak bude uživatelská příručka, což bude po technické stránce prakticky totéž.

Po vzoru knížky ProGit chci celou dokumentaci dát do samostatného repositáře Gitu a napsat to v nějakém plaintextovém formátu, který půjde diffovat a mergovat. Repositář se pak do aplikace přilinkuje jako submodul (či něco podobného) a aplikace se postará o zobrazení dokumentace uživateli.

Pro zobrazování dokumentace nechci používat externí nástroje. To by přidělávalo práci s deploy a editací. Konverzi do HTML tedy musí zvládnout nějaká PHP knihovna přibalená k aplikaci. Konverze do LaTeXu už mne nepálí, tam se nějaký build script použije tak jako tak.

Vzhledem k podpoře na GitHubu a všeobecné rozšířenosti jsem zatím došel k Markdown, jakožto formátu samotného textu. Na první pohled to vypadá nadějně, ale ... neumí číslovat obrázky ani kapitoly, odkazovat na čísla kapitol, generovat obsah, vlastní odkazy, ... takže je vlastně nepoužitelný na cokoliv většího než pár odstavců.

Existuje něco jiného, co je dostatečně rozšířené?

V čem píšete dokumentaci vy?

Odpovědi

[lertimir]

A co Docbook?

[Josef Kufner]

Na dokumentaci je nejdůležitější, aby se snadno psala. Docbook to s tím šíleným XML vůbec nesplňuje

[lertimir]

Připadá mi, že je věc jednak zvyku a jednak dobrého XML editoru. Pro někoho LaTeXový dokument je také napsaný "šíleným" jazykem. Zkusil bych XMLmind, které je i linuxové (javové) prostředí. DocBook mi připadá jako přirozené prostředí pro dokumentaci, která potřebuje generovat různé výstupy.

[Josef Kufner]

Ono nejde jen o vlastní editaci, ale také o diffy a mergování změn. Tam už to začne být šťanatější.

Navíc pokud to bude v Markdown nebo něčem podobně podporovaném, tak kdokoliv může na GitHubu zmáčknout čudlík "Edit" a velice pohodlně opravit/připsat, co chce, jen s použitím prohlížeče a poslat pull request. To dává trochu lepší šance na udržení dokumentace aktuální.

[alfonz]

přesně tohle se sphinxem a rst funguje ...

více viz

http://sphinx-doc.org/ http://docutils.sourceforge.net/rst.html http://rst2pdf.ralsina.com.ar/quickstart.html

v případě potřeby se pak pouze vytvářejí nové rst soubory nebo se Sphinx nastaví na automatické skládání. Umí to pak i LaTeX.

Sphinx lze pak nastavit, že dělá automaticky Obsah, Index (mohou být i číslované).. Vkládání souborů obrázků (lze řešit i vložení PDF/SVG)

http://sphinx-doc.org/sphinx.pdf a tady je ukázka PDF přes LaTeX a zde

přes http://sphinx-doc.org/sphinx-rst2pdf.pdf

[dustin]

Ten sphinx vypadá opravdu pěkně a seznam projektů, které jej využívají, je pořádně dlouhý.

[Josef Kufner]

Jo, Sphinx vypadá opravdu pěkně. Pokud se neobejdu bez exteního nástroje pro vyrobení HTML, asi ho použiju. Raději bych však, aby mi PHP aplikace nezávisela na Pythonu.

[alfonz]

tak lze použít pouze rst2html > ale to je také závislé na pythonu myslím

[alfonz]

jinak zde se píše o PHP aplikaci https://github.com/chobie/PHP_reStructuredText a tam je dále napsáno tohle

currently this library has not maintained. please use rst2xml and parse it. možná existuje ještě nějaká lepší knihovna.. Na druhou stranu, rst je přímo podporavné na githubu, takže si myslím, že to je v pohodě

možná ta zmíněná php knihovna stačí.

[alfonz]

řešil jsem podobný problém a vyřešil přes Sphinx + rst2html/rst2pdf Dá se to jednoduše připojit i k dokumentaci generované sphinxem a k tomu přidat pár vlastních python skriptů pro úpravy dokumentace a je to v pohodě.

popravdě jsem s vámi chtěl i pár věcí probrat více předtím..

[alfonz]

a už jsem to nedopsal.. no nějak se s vámi ještě zkusím zkontaktovat