
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::".

[obrázek]

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.

   /* 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:

   (a + b)^2  &=  (a + b)(a + b) \\            &=  a^2 + 2ab + b^2

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.


A co dál?
=========

Sphinxové weby

* Sphinx: Python Documentation Generator

* Python 2 documentation

* Python 3 documentation

* GMT 5 documentation

* Fortran 90 Ondřeje Čertíka

Výňatky z dokumentace

* HTML témata

* Konfigurační soubor

* Matematické vzorce


Jmenný rejstřík
===============

* A

* B

* C

* *Rejstřík*

* *Vyhledávací stránka*
