Sphinx
======
Dokumentace se zkompiluje příkazem `` ` make html ` `` ve složce `` ` doc ` `` .
Složka `` ` modules ` `` je automaticiky generována a přegenerovávána. (Nic v ní neupravovat!)
Jinak všechny rst, co jsou ve složce `` ` doc ` `` a jejích podsložkách nezačínajících podtržítkem, budou v dokumentaci a to je přesně to, co editovat pro změnu dokumentace (kromě dokumentace přímo v Pythonu).
Sphinx se píše v rst: `Návod na syntaxi rst`_
Problém
-------
U mě `` ` make html ` `` vůbec nereagoval na změny `` ` Makefile ` `` , tedy jsem `` ` sphinx-apidoc... ` `` nakódil přímo do `` ` conf.py ` `` .
make html
---------
Make html dělá následující: Vygenerují se rst soubory do modules z pythoní dokumentace pomocí:
`` ` sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f ` ``
- `` ` --module-first ` `` říká, že dokumentace modulu má být dřív než to, co obsahuje,
- `` ` -o ` `` je výstupní složka příkazu,
- `` ` .. ` `` prochází složku mamweb,
- `` ` ../*/migrations ` `` ignoruje migrace
- `` ` --templatedir _templates ` `` určuje templaty, podle kterých se vyrábí rst z Pythoní dokumentace a struktury složek a souborů,
- `` ` -f ` `` donutí phinx znovu přegenerovat soubory, protože nepozná, že se nějaká dokumentace změnila)
Poté se spustí „samotný sphinx“ a vygenerují se soubory v `` ` _build/html ` `` .
.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections