Dokumentace make skriptů

docs/skripty.rst

@@ -0,0 +1,108 @@
+Skripty pro práci s repozitářem
+===================
+
+Máme dvě hlavní sady skriptů/příkazů na ovládání webu a repozitáře. Skripty pro
+práci s webem psané v Pythonu jsou uložené ve složkách
+``<aplikace>/management/commands/``, případně vestavěné, a volají se pomocí
+``./manage.py <příkaz>``. Oproti tomu skripty pro práci s repozitářem a pro
+úpravy databáze a souborů „zvenčí“ se nejčastěji nacházejí ve složce ``make/``
+a volají se pomocí cesty: ``make/<příkaz>``.
+
+Občas existují i nějaké další skripty na různých jiných místech. Všechny by
+měly být ideálně popsány asi tady.
+
+Make skripty
+----
+
+Skripty v ``make/`` se označují jako „Make skripty“. Slouží často k velkým
+úkonům s repozitářem, jako je nasazení celého webu, zprovoznění lokálního webu
+a podobně.
+
+.. hint:: Označení pro tyto skripty je dáno tím, že byly původně volány pomocí
+   make (tj. z Makefile). Ve skutečnosti je lze stále volat i jako ``make
+   <skript>``, ale pak není možné předávat parametry a obecně je tato cesta
+   zastaralá a existuje jen pro zpětnou kompatibilitu se svalovou pamětí.
+
+Tyto skripty jsou samonosné, dají se spustit rovnou a v případě problémů si
+budou hlasitě stěžovat. Pro účely debugování různých věcí jsou ale (bohužel?)
+hlasité i při normálním spuštění, konkrétně vypisují všechny příkazy, které se
+spouštějí (\ ``set -x``). Tyto příkazy jsou vidět za jedním či více plusky (\ ``+``).
+
+.. tip:: Pokud některý make skript selže, tak by na konci měl vypsat, že se něco nepovedlo.
+
+
+Knihovna ``make/lib.sh``
+^^^^^^
+
+Pro pohodlí při psaní velká část z nich využívá knihovnu uloženou
+v ``make/lib.sh``. Jsou zde definované užitečné proměnné, kontroly a společný
+kód. Kromě toho při inicializaci otestuje, že je skript spuštěn z kořene
+repozitáře (takže to pak není potřeba zkoumat v ostatních skriptech).
+
+Proměnné
+"""""
+
+Popsány jsou jen užitečné proměnné, ve skutečnosti jich je definovaných víc,
+ale jsou triviální a samopopisné.
+
+``VENV_PATH`` :
+  Cesta virtuálního prostředí. Též lze přepsat.
+``REPO`` :
+  Cesta ke gitovému repozitáři na serveru, rovnou použitelná v ``git clone``
+``GIMLI_LOGIN`` :
+  Přihlašovací údaje ke Gimlimu
+``PRODWEB`` a ``TESTWEB`` :
+  Cesty ke složkám s produkčním a testovacím webem
+
+Funkce a další zkratky
+""""""
+
+``ensure_venv`` :
+  Zajistí, že se zbytek skriptu spustí ve virtuálním prostředí, a pokud neexistuje, tak jej založí.
+``ensure_web_installed`` :
+  Vyzkouší, že je web (django) aspoň elementárně zprovozněno a pokud ne, tak vyzve uživatele, aby to spravil.
+``gimli_only`` :
+  Otestuje, že je příkaz spuštěn na Gimlim, pokud tomu tak není, zeptá se, jestli si uživatel skutečně přeje zbytek skriptu vykonat
+``only_in_directory <složka>`` :
+  Otestuje, že skript běží z konkrétní složky. Zejména použitelné s ``gimli_only`` a ``$TESTWEB``
+``safe_checkout_branch <větev>`` :
+  Bezpečně přepne repozitář na jinou větev. Pokud by mělo dojít k přepsání
+  knihovny nebo volajícího make skriptu, vyzve uživatele, aby přepnul ručně.
+``install_everything`` :
+  Společná část kódu pro nasazování produkce a testwebu.
+
+Skripty pro lokální vývoj
+^^^^^^^
+
+``make/install_web`` (nebo ekvivalentně ``make/install``) :
+  Vytvoří virtualenv a nainstaluje do něj závislosti webu podle ``requirements.txt``. Následně popíše, jak vyrobit zbytek lokálního webu.
+``make/run`` :
+  Spustí lokální web (ekvivalentní s ``./manage.py runserver``)
+``make/schema`` :
+  Vykreslí závislosti a atributy modelů
+``make/sync_prod_flatpages`` :
+  Stáhne z produkce aktuální statické stránky a uloží je do složky ``data/``
+``make/test`` :
+  Spustí testy (ekvivalentní s ``./manage.py test -v2``)
+``make/init_local`` :
+  Zkratka za posloupnost ``make/install_web``, ``./manage.py testdata``, ``./manage.py loaddata data/*``, ``make/sync_prod_flatpages``
+
+Práce s testwebem
+^^^^^^^
+
+``make/deploy`` :
+  Nasadí testweb. Volitelně bere jako parametr jméno větve, kterou má nasadit.
+  Rovnou nastaví přihlašování a vygeneruje příslušnou verzi dokumentace `sem <https://mam-test.ks.matfyz.cz/docs>`_.
+``make/push_compiled_vue_to_test`` :
+  **Neotestováno** Nahraje Vue z lokálního počítače na testweb. (Gimli často má moc starou verzi Node.js, takže nejde zkompilovat tam)
+``make/sync_test_db_aggressive`` :
+  Zkopíruje databázi z produkčního webu.
+``make/sync_test_media`` :
+  Zkopíruje média (obrázky, nahrané soubory) z produkčního webu.
+``make/sync_test`` :
+  Zkratka za ``make/sync_test_db_aggressive`` + ``make/sync_test_media``.
+
+Nasazení produkce
+^^^^
+
+``make/deploy_prod``. Před samotným nasazením zálohuje databázi a zkontroluje, že se nasazuje větev ``master``.