Sphinx na našem webu
====================
Dokumentace se zkompiluje příkazem `` make html `` ve složce `` docs `` .
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 `` docs `` 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`_ `Cheat sheet`_
Pokud něco chcete protlačit do bočního meníčka, je potřeba to připsat do souboru `` docs/index.rst `` (Zatím není úplně konsensus nad tím, co tam má a nemá být, takže pokud si nejste jistí, cpěte tam *všechno* ☺)
To je snad vše, co je potřeba vědět k dokumentaci mamwebu. Následující sekce jsou o tom, co jsem provedl Sphinxu, aby to fungovalo:
.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections
.. _Cheat sheet: https://sphinx-tutorial.readthedocs.io/cheatsheet/
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 `` .
Templates
---------
Templaty jsou originální s pár změnami:
- Změnil jsem nadpisy
- Odstranil jsem některá slova v nadpisech (module, package, …)
- Odstranil jsem nadpis Subpackages
přišlo mi to takhle lepší. Ale stále nejsem moc spokojen, protože je to pořád nepřehledné.
