Navigace

Poprvé se Sphinxem

Co to? Proč to?

Sphinx je pythonovský balíček primárně určený pro vytváření softwarové dokumentace, sekundárně pak pro vytváření obecných dokumentů v populárních formátech. Zdrojovým kódem je speciálně formátovaný textový soubor; člověk může dlouho vydržet s celkem dobře zapamatovatelným zlomkem sphinxovské syntaxe. Překládá se předchystaným skriptem, výstupem mohou být formáty HTML, PDF, LaTeX, prostý text a další. Pro správnou interpretaci češtiny stačí ukládat v kódování UTF-8. Užitečnost zvyšuje podpora texovské syntaxe pro vzorce s výstupem i do HTML - cílové rovnice jsou buď PNG obrázky nebo syntaxe, k jejíž interpretaci se stránka obrací na vnější webovou aplikaci MathJax.

Instalace balíčku. Inicializace a překlad projektu

Těžko lze snáze. Balíček se opatří obvyklým pythonovským způsobem nebo, např. v Ubuntu, obvyklým ubuntuvským způsobem,

easy_install sphinx
apt-get install python-sphinx

Projekt se inicializuje příkazem

sphinx-quickstart

a následnou interakcí. Na pokládané otázky lze vesměs odpovědět akceptováním defaultu; odpovědět je nutno na otázku po názvu projektu a autora a rozhodnout se je třeba u volby zpracování texovských vzorců. Stojí za to zkusit si obě nabízené možnosti, pngmath a mathjax. (Vybrat je třeba nejdřív jednu, jindy druhou.) Vzniknou potřebné adresáře pro zdroje i výstupy, konfigurační soubor conf.py a překladové skripty. V conf.py se naleznou jak odpovědi ze vstupního dotazování, tak řada přednastavených hodnot, vše otevřeno dalším změnám. Např. počeštění sphinxových textů ve výstupních souborech se dosáhne změnou language = 'cs' (kód jazyka je řetězec v apostrofech), jinak lze volit de, en, es, fr, sk ad. Pro HTML jsou k mání volby pro nastavení výstupního vzhledu čili tématu, pro nastavení různých režijních textů, pro LaTeX třeba velikost písma.

Dál se už edituje předchystaný soubor index.rst (formát reStructuredText alias reST s rozšířeními pro Sphinx) a volitelně vytvářejí další navázané soubory. Pro překládání je připraven buď konfigurační soubor pro make nebo, není-li make ve Windows k dispozici, dávkový soubor make.bat. Argumentem jednoho i druhého volání make je výstupní formát:

make html
make latexpdf
make latex ; cd _build/latex ; make
make text

a několik dalších. Výstupy se formují v podadresářích adresáře _build; latexovský výstup je třeba dále překládat, k čemuž je u něj přichystán další Makefile.

reST formátování

Odstavce, odsazené ukázky, seznamy, direktivy ad. se oddělují od okolí prázdným řádkem. Důležité je udržování pythonovského odsazování textových struktur zleva. Hlavní nadpis je podtržen rovnítky ===, vedlejší nadpisy pomlčkami ---, v další úrovni stříškami ^^^. Kurzíva je mezi hvězdičkami, tučný text mezi dvojhvězdami, podbarvený text mezi dvojitými zpětnými apostrofy. Položky nečíslovaných seznamů začínají hvězdičkou, číslované položky křížkem s tečkou nebo explicitním číslováním. Vnořování seznamů je možné. Pro naše i cizokrajné znaky je třeba zdrojový soubor kódovat v UTF-8 (with signature).

Ukázka vnořených seznamů:

  • československá diakritika
    • Příliš žluťoučký kůň úpěl ďábelské ódy.
    • PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY.
    • Príliš žltý kôň volal diabolské ódy.
    • PRÍLIŠ ŽLTÝ KÔŇ VOLAL DIABOLSKÉ ÓDY.
  • cizokrajná diakritika
    • Too yellow horse moaned devilish odes.
    • Zu gelb Pferd stöhnte teuflischen Oden.
    • Слишком желтый лошадь застонала дьявольские оды.
    • 太黃馬呻吟著惡魔般的讚歌。
    • あまりにも黄色の馬は悪魔のような微分方程式をうめいた。

Číslovaný seznam:

  1. Položka číslovaného seznamu
  2. Další položka
Definice
Text definice se prostě jen odsadí.

Tabulky mohou mít více podob, nejjednodušší je tato:

jméno světec
Petr ano
Pavel ano

Pro webové odkazy jsou připraveny jednoduché zpětné apostrofy: odkaz na web jednookých je zapsán takto: `web jednookých <http://karel.troja.mff.cuni.cz/jednooci_slepym>`_. Obrázky je zvykem umístit do adresáře _static a odkázat direktivou .. image:: _static/figura.jpg, pro obrázky s legendou direktivou .. figure::.

_images/figura.jpg

Je definována řada dalších direktiv pro různě vyznačené odstavce, citace, poznámky “pod čarou” [1], substituce apod.

[1]Poznámka k poznámce “pod čarou”.

Fortranské ukázky

Ukázky “ukázek kódů”, to už tady bylo, a už je to tu zas. Odstavec se ukončí čtyřtečkou ::, následující kód se odsadí a máme toto:

! Fortran 95
real(8) pi
pi=atan(1._8)*4.

! Fortran 2003
real(8),parameter :: pi=atan(1._8)*4.

Lze si vyžádat číslování řádků; pro některé programovací jazyky (Python, C, nikoliv Fortran) je definováno barevné zvýraznění syntaxe.

1
2
3
/* C */
double pi=atan(1.)*4.;
printf("pi = %f",pi);

Matematické vzorce

Syntaxe vzorců je převzata z TeXu. Vzorce v textu následují po :math:`...`, např. tento malý: \(c=\sqrt{a^2+b^2}\), pro odsazené vzorce je určeno .. math::. Větší vzorec se zarovnáním:

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

Výbava je v rozsahu schopností balíčku AMS-LaTeX. Několik dalších detailů je v návodu Math support in Sphinx - jak rovnice číslovat, jak na ně odkazovat.

Překlad a zobrazení si latexovské formáty zajistí samy, do HTML buď pngmath (s podporou instalovaného LaTeXu a dvipng) připraví hotové PNG snímky rovnic nebo se ponechá symbolický zápis as-is, který pak interpretuje javascriptová aplikace MathJax při online zobrazení stránky. Výsledky nevypadají zcela shodně, ale obojí je pěkné, i třeba při zobrazení přes NX klient. Přepíná se před překladem v konfiguračním souboru conf.py, MathJax (včetně fontů) se bere buď z jejich webu nebo se může uložit na lokálním serveru.

Jmenný rejstřík

Obsah

Tato stránka

Navigace

Vytvořeno pomocí Sphinx 1.2.1.