Sepsané zkratky pro zdrojáky

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/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.