Web M&M
https://mam.matfyz.cz
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.
75 lines
3.4 KiB
75 lines
3.4 KiB
Sphinx na našem webu
|
|
====================
|
|
|
|
(Návrh) rozložení/členění dokumentace
|
|
-------
|
|
|
|
.. note:: Předpokládám, že tohle je dočasné a že v případě schválení návrhu se
|
|
obsah odsud objeví nejspíš na titulní stránce dokumentace. Zatím je tady pro
|
|
diskusi, ale rozhodně může být jinde a jinak napsaný…
|
|
|
|
Představuji si aktuálně tříúrovňovou dokumentaci:
|
|
|
|
#. Několik málo (určitě ne víc než deset) stránek pro seznámení s webem,
|
|
repozitářem apod. Ty by byly spíš povrchové a prostě by cílily na novowebaře
|
|
a snažily se ho seznámit s našimi postupy
|
|
- Intro rozcestník
|
|
- Jak rozběhnout lokální web
|
|
- Jak u nás funguje vývoj webu (úzy, coding style, pull-request workflow, tři instance webu a jak je použít, …)
|
|
- Co kde je (aplikace, jak dohledat view k URL)
|
|
- Možná historie webu (zejména pro zajímavost, ale i pro nějaký náhled, co si táhneme s sebou za historii…)
|
|
- Popis částí Djanga (můj fancy obrázek, jen nakreslený použitelněji :-))
|
|
#. Freetextová dokumentace k různým částem webu, sepsaná v ``docs/``.
|
|
- Různé tipy (aktuálně sepsané na wiki)
|
|
- Textovější popis různých věcí
|
|
- Dokumentace ne-pythonu (make skripty)
|
|
- …
|
|
#. Autogenerovaná reference z docstringů
|
|
|
|
Nepředstavuji si, že by všechno bylo na všech třech úrovních, spíš naopak dává
|
|
smysl se mezi úrovněmi odkazovat a neduplikovat.
|
|
|
|
Bylo by fajn, kdyby ta intro /
|
|
tutoriálová část byla spíš stručnější, ale pokud ji budu psát já, tak to zase
|
|
nedopadne :-) (ale asi je lepší, když bude nějak, než když nebude vůbec)
|
|
|
|
|
|
Použití
|
|
------
|
|
|
|
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`_ `Cheat sheet`_
|
|
|
|
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é.
|
|
|