| 10 | ||
|
Editor: geon
Time: 2009/02/21 16:28:01 GMT+1 |
||
| Note: | ||
changed: - 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: - píšete skutečně lidsky, žádné rušící html značky. "Lidsky" je jiné slovo pro rst. Jazyk rst byl vyvinut hlavně pro přehledné psaní textů. Dost se podobá psaní na starých psacích strojích. - z rst do html vám pomůže právě sphinx. Kromě toho, že doplní všechny html značky, umí navíc ještě následující: - vytváří index klíčových slov - vytváří vyhledávací pole - vytváří index modulů - a mnoho dalšího - vypadá graficky profesionálně - odpovídá stylu dokumentace k Python 3.0 - přes css je možnost úprav - a mnoho dalšího 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`` .. _easy_install_setup: http://peak.telecommunity.com/dist/ez_setup.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 Záložky ----------- - http://sphinx.pocoo.org/ - http://sphinx.pocoo.org/contents.html - http://sphinx.pocoo.org/sphinx.pdf - http://groups.google.com/group/sphinx-dev
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:
píšete skutečně lidsky, žádné rušící html značky. "Lidsky" je jiné slovo pro rst. Jazyk rst byl vyvinut hlavně pro přehledné psaní textů. Dost se podobá psaní na starých psacích strojích.
z rst do html vám pomůže právě sphinx. Kromě toho, že doplní všechny html značky, umí navíc ještě následující:
- vytváří index klíčových slov
- vytváří vyhledávací pole
- vytváří index modulů
- a mnoho dalšího
vypadá graficky profesionálně
odpovídá stylu dokumentace k Python 3.0
přes css je možnost úprav
a mnoho dalšího
Následující postup platí jak pro Linux, tak pro Windows.
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
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.
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
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
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