From 3920ac72aaa66fc16f94193194465123389c0a7a Mon Sep 17 00:00:00 2001 From: "Pavel \"LEdoian\" Turinsky" Date: Tue, 19 Nov 2024 22:38:34 +0100 Subject: [PATCH 1/3] =?UTF-8?q?Sepsan=C3=A9=20zkratky=20pro=20zdroj=C3=A1k?= =?UTF-8?q?y?= 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. From 36b261580c9f0c17958f99b7826f695050260a54 Mon Sep 17 00:00:00 2001 From: "Pavel \"LEdoian\" Turinsky" Date: Tue, 19 Nov 2024 22:38:46 +0100 Subject: [PATCH 2/3] =?UTF-8?q?Aktualizace=20toho,=20jak=20se=20pou=C5=BE?= =?UTF-8?q?=C3=ADv=C3=A1=20Sphinx=20u=20n=C3=A1s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/sphinx.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/sphinx.rst b/docs/sphinx.rst index 6a9b7a53..67ea440b 100644 --- a/docs/sphinx.rst +++ b/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``. 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 From 5f87045b315c4a3de2aa332ca6c6549454811ab6 Mon Sep 17 00:00:00 2001 From: "Pavel \"LEdoian\" Turinsky" Date: Tue, 19 Nov 2024 22:39:18 +0100 Subject: [PATCH 3/3] =?UTF-8?q?Je=C5=A1t=C4=9B=20jedna=20aktualizace=20:-)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/sphinx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx.rst b/docs/sphinx.rst index 67ea440b..b450375c 100644 --- a/docs/sphinx.rst +++ b/docs/sphinx.rst @@ -1,7 +1,7 @@ Sphinx na našem webu ==================== -Dokumentace se zkompiluje příkazem ``make html`` ve složce ``docs``. +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 ``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).