Sphinx

Program (modul), který pomáhá při psaní dokumentace. Nic za vás nenapíše, ale může ušetřit čas a nervy. Následují výhody hlavně oproti psaní dokumentace přímo v html:

Následující postup platí jak pro Linux, tak pro Windows.

Instalace

Stažení a instalace je doporučována přes easy_install. Kdo má, stačí napsat:

easy_install sphinx

Kdo nemá easy_install, stáhne nejdřív easy_install_setup, spustí, tím se mu nainstaluje easy_install do PythonXX/Scripts.

Kdo je odvážný, mohl by zkusit nainstalovat poslední vývojovou (dev) verzi, která může obsahovat chyby, ale za to obsahuje mnoho nových vlastností. (Aby vám toto fungovalo, musíte vlastnit svn (subversion). Na Linuxu je instalace prostá, Windows musí nainstalovat např. http://www.sliksvn.com/en/download):

svn co http://svn.python.org/projects/doctools/trunk/ sphinx-dev
cd sphinx-dev
setup.py install

Pokud chcete mít české popisky (místo Next topic mít Další téma atd.), přidejte language="cs" do souboru conf.py

Čistá louka

Nemáte nic napsaného a chcete si vytvořit základní strukturu. Pusťe z PythonXX/Scripts

sphinx-quickstart

a pravdivě odpovídejte na všechny otázky.

Psaní dokumentace

Ve vzniklé složce vytvořte např. pokus.rst. Minimálně v něm musí být jeden nadpis, takže např:

Pokusný nadpis
=================

Toto je můj první pokus o dokumentaci ve Sphinx.

Pište lidsky, tedy tak jak velí rst. Je nutné ukládat ve formátu UTF-8, jinak nefunguje čeština. Dále edituje index.rst, a doplňte k toctree:

.. toctree::
   :maxdepth: 2

   pokus

Generace html

Můžete buď využít příkaz sphinx-build -b html odkud kam nebo použít dávku make.bat, která by vám měla v průběhu vytváření základní struktury vzniknout ve složce s index.rst. Je třeba v ní upravit cestu k sphinx-build někde hned na začátku, například takto:

set SPHINXBUILD=c:\python26\Scripts\sphinx-build

Spusťte dávku make.bat bez parametrů a vypíše se vám nápověda. Asi nejčastější použití bude:

make html

Převod staré dokumentace HTML na RST

Chcete-li převést svoji starou html dokumentaci na rst doporučuji script http://bazaar.launchpad.net/~grflanagan/python-rattlebag/trunk/annotate/head:/src/html2rest.py. Je však třeba nejdříve převést všechny své html na utf-8.

Použití je pak následující:

html2rest.py vstupni_soubor > vystupni_soubor