Merge pull request 'Dokumentace zkratek do zdrojáků' (!77) from doc_zkratky into master

Reviewed-on: #77

docs/index.rst

@@ -30,6 +30,7 @@ Dokumentace (jak v ``docs/``, tak přímo v kódu) je psaná ve
    zavislosti
    sphinx
    skripty
+   zkratky
    modules/modules
    dalsi_soubory
    zapisy/zapisy

docs/sphinx.rst

@@ -1,13 +1,15 @@
 Sphinx na našem webu
 ====================
 
-Dokumentace se zkompiluje příkazem ``make html`` ve složce ``doc``.
+Dokumentace se zkompiluje příkazem ``make html`` ve složce ``docs``. (Musíte mít zapnutý virtualenv)
 
 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).
+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

docs/zkratky.rst

@@ -0,0 +1,86 @@
+Zkratky aplikací ve zdrojácích
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+Ve zdrojácích (zejména různé ``models.py``, ``views.py`` ap.) používáme spoustu
+modelů. Někdy je praktičtější / někdo preferuje importovat celou aplikaci jako
+jedno jméno a používat modely bez explicitních importů, tj::
+
+    # „hromadné“ importy:
+    import personalni.models as p
+    ...
+    p.Organizator.objects.all()
+
+    # „explicitní“ importy:
+    from personalni.models import Organizator
+    ...
+    Organizator.objects.all()
+
+Na webschůzce 2024-11-05 jsme na toto téma otevřeli diskusi, tady je její závěr.
+
+.. admonition:: Historické okénko
+   :class: note
+
+   Kdysi jsme měli (prakticky) všechny modely v jedné aplikaci, ``seminar``. Na
+   různých místech se pak ``seminar.models`` importovalo typicky jako ``s``
+   nebo jako ``m``.
+
+   Přirozeně, toto už nejde tak snadno, protože už neexistuje jedno místo, ze
+   kterého chceme tahat modely v kódu.
+
+Konvence
+========
+
+Shodli jsme se, že nám rozhodně nevadí explicitní importy a z pohledu
+čitelnosti je preferujeme. Nicméně při psaní kódu to některým webařům přijde
+nepohodlné, takže očekáváme, že bude existovat spousta kódu, která bude chtít
+importovat hromadně. Usnesli jsme se proto na následujících kanonických
+zkratkách, aby se aplikace alespoň zkracovaly konzistentně.
+
+V závorkách je uvedené případné jméno, ale nepředpokládáme, že někdo bude danou
+aplikaci chtít importovat hromadně. Některé aplikace zkratku nemají, ty se
+importují vždy pod plným jménem nebo explicitně.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Model
+     - Zkratka
+   * - ``aesop``
+     - ---
+   * - ``api``
+     - --- (``api``)
+   * - ``galerie``
+     - ``g``
+   * - ``header_fotky``
+     - --- (``hdr``)
+   * - ``korektury``
+     - ``kor``
+   * - ``novinky``
+     - ``nov``
+   * - ``odevzdavatko``
+     - ``odev``
+   * - ``personální``
+     - ``pers``/``p``
+   * - ``sifrovacka``
+     - (``sifr``)
+   * - ``soustredeni``
+     - ``sou``
+   * - ``treenode``
+     - ``tn``
+   * - ``tvorba``
+     - ``tv``
+   * - ``various``
+     - ``v``/``var``
+   * - ``vyroci``
+     - ---
+   * - ``vysledkovky``
+     - ``vysl``
+
+
+.. admonition:: O všech modelech pod jedním jménem
+   :class: warning
+
+   Historické okénko výš zatajuje jeden detail: Při práci v shellu se hodí mít
+   modely k dispozici a nemuset přemýšlet nad dělením do aplikací, takže ve
+   skutečnosti existuje ``mamweb.vsechno``, jenž všechny modely obsahuje.
+   Z čitelnostních důvodů je ale *zakázáno* tento modul používat v kódu.