﻿.. Ukázka dokumentování ve Sphinxu
   
   Komentář může být víceřádkový, vyznačený odsazením.

Poprvé se Sphinxem
==================

.. toctree::
   :maxdepth: 2

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

#. Položka číslovaného seznamu
  
#. 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 <http://karel.troja.mff.cuni.cz/jednooci_slepym>`_ 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::``.

.. image:: _static/figura.jpg

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

.. rubric: Footnotes

.. [#f1] Poznámka k poznámce "pod čarou".

Fortranské ukázky
-----------------
.. highlight:: none
   :linenothreshold: 5

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.

.. highlight:: c
   :linenothreshold: 1

::

  /* 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ý: :math:`c=\sqrt{a^2+b^2}`, pro odsazené vzorce je určeno ``.. math::``. Větší vzorec se zarovnáním:

.. math::

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

Výbava je v rozsahu schopností balíčku `AMS-LaTeX <http://www.ams.org/publications/authors/tex/amslatex>`_. Několik dalších detailů je v návodu `Math support in Sphinx <http://sphinx-doc.org/latest/ext/math.html>`_ - 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 <http://www.mathjax.org>`_ 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 <http://sphinx-doc.org/index.html>`_
* `Python 2 documentation <https://docs.python.org/2/>`_
* `Python 3 documentation <https://docs.python.org/3/>`_
* `GMT 5 documentation <http://gmt.soest.hawaii.edu/doc/5.1.1/index.html>`_
* `Fortran 90 Ondřeje Čertíka <http://www.fortran90.org/>`_

Výňatky z dokumentace

* `HTML témata <http://sphinx-doc.org/theming.html>`_
* `Konfigurační soubor <http://sphinx-doc.org/config.html>`_
* `Matematické vzorce <http://sphinx-doc.org/latest/ext/math.html>`_

Jmenný rejstřík
---------------
* A
* B
* C
* :ref:`genindex`
* :ref:`search`
