You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

41 lines
1.7 KiB

Sphinx na našem webu
====================
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`_
.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections
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``.
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é.