From 3920ac72aaa66fc16f94193194465123389c0a7a Mon Sep 17 00:00:00 2001
From: "Pavel \"LEdoian\" Turinsky" <ledoian@matfyz.cz>
Date: Tue, 19 Nov 2024 22:38:34 +0100
Subject: [PATCH] =?UTF-8?q?Sepsan=C3=A9=20zkratky=20pro=20zdroj=C3=A1ky?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/index.rst   |  1 +
 docs/zkratky.rst | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 docs/zkratky.rst

diff --git a/docs/index.rst b/docs/index.rst
index d06c7e4a..af3b0c12 100644
--- a/docs/index.rst
+++ b/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
diff --git a/docs/zkratky.rst b/docs/zkratky.rst
new file mode 100644
index 00000000..95902921
--- /dev/null
+++ b/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.