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/sphinx.rst b/docs/sphinx.rst index 6a9b7a53..b450375c 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``. (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 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.