Dokumentace lokálního vývoje

Obsahuje tipy z Readme, obsahuje velkou část make/README.md.

Zatím nevím, co provedu s make/README.md, ale na něco třeba přijdu :-)

docs/vyvoj.rst

@@ -1,20 +1,181 @@
 Lokální vývoj mamwebu
 =====================
-Stačí spustit::
 
-    ## Nahradte svym gimli username
-    git clone USER@gimli.ms.mff.cuni.cz:/akce/mam/git/mamweb.git mamweb
-    cd mamweb
-    ## Instalace je trochu magická, spusť následující posloupnost příkazů:
-    make install_venv
-    . env/bin/activate
-    make install_web
+Asi hlavní část vývoje většiny webu probíhá lokálně. Každý tak může pracovat na
+vlastních úpravách nezávisle na ostatních.
 
-    ## Vygeneruje nejaka testovaci data (spis chuda)
-    ./manage.py testdata
-    ## Nahraje statické stránky, menu a obrázky v pozadí menu
-    ./manage.py loaddata data/*
-    ## Spusti testovaci server na http://127.0.0.1:8000/
-    ./manage.py runserver
+Potřebné vybavení
+-------
+
+Tento soupis cílí na nějakého typického vývojáře webu – Linuxáka. Jistě je
+spousta dalších možností, které zde nejsou postihnuty – poraď se s webaři,
+pokud si nejsi jistý. (Speciálně lze nějak vyvíjet na Windows, leč lze často
+narazit na odlišné chování od Linuxu.)
+
+Motivace cílení na Linux je to, že Gimli je Linuxový stroj, takže je vývojové
+prostředí pak podobné produkci a zmenšuje to množství odlišného chování.
+
+.. TODO: Na dokumentaci odlišného chování (Postgres vs. SQLite, Win vs. Linux, …)
+   by to asi chtělo výhledově separátní stránku, ale teď píšu tuhle :-)
+
+Nutné
+^^^^
+
+- `Git <https://git-scm.com>`_
+- `Python <https://python.org>`_
+
+  - Ideálně ve verzi 3.9 (to je to, co je aktuálně (2022) na Gimlim)
+  - Včetně pip-u (na Ubuntu balíček ``python3-pip``) a knihoven pro kompilaci
+    Cčkových rozšíření (``python3-dev``)
+- Knihovna pro práci s PostgreSQL (``libpq-dev``)
+- Webový prohlížeč
+- \*NIXový shell (typicky ``bash``)
+
+.. TODO: Pokud tu něco chybí, tak to dopiš :-)
+
+Kromě toho je potřeba mít účet na `Gitee <https://gitea.ks.matfyz.cz>`_, kde
+bydlí gitový repozitář s kódem.
+
+Doporučené
+^^^^^^^^^^
+
+- Python wheel (možná řeší problémy s potřebou ``-dev`` balíčků…)
+- Editor / IDE podporující `Editorconfig <https://editorconfig.org/>`_
+- Uživatelská zkušenost s `produkční verzí webu <https://mam.matfyz.cz>`_
+- Účet v `Kanci <https://kanboard.ledoian.cz>`_
+
+.. TODO: A nejspíš další věci, na které jsem si teď nevzpomněl.
+
+
+Zprovoznění
+-------
+
+Nejprve je potřeba stáhnout si repozitář. To se provede příkazem ``git clone
+https://gitea.ks.matfyz.cz/mam/mamweb.git``, případně ``git clone
+git@gitea.ks.matfyz.cz:mam/mamweb.git``, pokud už máš nahraný SSH klíč na
+Giteu. (Obě adresy se dají zkopírovat ze `stránky repozitáře
+<https://gitea.ks.matfyz.cz/mam/mamweb>`_.) To vyrobí složku ``mamweb``, přepni
+se do ní (``cd mamweb``)
+
+O zprovoznění webu se stará skript ``make/install_web``, stačí ho spustit. Ten
+vytvoří virtualenv (neexistuje-li) a nainstaluje do něj závislosti webu (podle
+souboru ``requirements.txt``).
+
+.. FIXME: Novowebaři zmínka o requirements.txt tady moc nepomůže, to má být na
+   stránce o celkové stavbě repozitáře a stacku…
+
+Následně je potřeba nahrát další data do databáze, což uděláš pomocí příkazů
+``./manage.py testdata`` a ``./manage.py loaddata data/*``. Skript
+``make/install_web`` to kdyžtak na konci připomene.
+
+.. caution:: Zatímco skripty v ``make/`` to nepotřebují, pro použití skriptu
+  ``./manage.py`` (a dalších) se potřebuješ přepnout do virtuálního prostředí.
+  To uděláš velmi pravděpodobně spuštěním ``source env/bin/activate``, před
+  začátkem *promptu* by se mělo objevit ``(env)``. Pro opuštění spusť
+  ``deactivate``.
+
+Samotný web se spustí třeba pomocí ``make/run``, nebo ekvivalentně
+``./manage.py runserver`` a pak je vidět na `<http://127.0.0.1:8000>`_.
+
+Časté problémy
+^^^^^^
+
+- ``make/install_web`` vypíše ``Error: pg_config executable not found.``:
+  Chybí ``libpq-dev``
+- Chybová hláška obsahuje ``#include <Python.h>``: chybí ``python3-dev``
+- Na webu není vidět meníčko: spusť ``./manage.py loaddata data/*``
+
+S dalšími problémy se zkus obrátit na další webaře, třeba někdo bude vědět :-)
+
+Příkazy pro ovládání webu
+-------
+
+Příkazy se dělí do několika skupin. Některé souvisí přímo s webem, Djangem,
+databází a podobně, ty typicky používají ``./manage.py``. Skripty pro
+obhospodařování repozitáře a webu „zvenku“ typicky bydlí ve složce ``make/``.
+Ostatní skripty jsou na náhodných místech :-)
+
+Tady jsou rozebrány jen příkazy relevantní pro lokální web a univerzálně
+užitečné, všechny by chtěly být sepsané jinde (ale zatím nejsou :-/)
+
+Make skripty
+^^^^^^^
+
+- ``make/install_web`` nainstaluje závislosti webu
+- ``make/run`` spustí web (ekvivalentní s ``./manage.py runserver``)
+- ``make/schema`` nakreslí schéma vazeb modelů (může se hodit pro referenci a představu)
+- ``make/test`` spustí testy (ale moc jich zatím není; ekvivalentní s ``./manage.py test``)
+- ``make/sync_prod_flatpages`` stáhne statické stránky z produkčního webu a
+  uloží je do souboru v gitu, což umožňuje jejich verzování
+- ``make/push_compiled_vue_to_test`` nahraje lokálně zkompilované části
+  frontendu ve Vue na testweb (Gimli má typicky moc starou verzi nodejs, takže
+  nejde kompilovat tam.)
+
+Manage.py skripty
+^^^^^
+
+.. note:: Je potřeba je spouštět ve virtuálním prostředí, viz výše.
+
+Všechny skripty kdyžtak mají ``--help``, dá se tak zjistit, co všechno umějí.
+
+- ``./manage.py testdata`` vygeneruje spíše chudá testovací data, aby bylo na
+  čem testovat web.
+- ``./manage.py loaddata <soubor/y>`` nahraje data ze souborů do databáze
+- ``./manage.py dumpdata <model>`` naopak z databáze vyrobí textovou reprezentaci
+- ``./manage.py shell`` spustí interaktivní pythoní shell, ze kterého lze
+  interagovat s webem / Djangem.
+- ``./manage.py dbshell`` spustí databázový shell (typicky používá SQL)
+
+- ``./manage.py makemigrations`` vyrobí popis migrací, ``./manage.py migrate``
+  je spustí, ``showmigrations`` ukáže, které migrace jsou aplikované a které
+  ne.
+- ``./manage.py runserver_plus`` spouští o něco lepší vývojový server (ale
+  nikdy jsem asi ty lepší featury nepoužil)
+
+Může se hodit vědět, že spuštění ``./manage.py`` bez parametrů vypíše seznam
+všech příkazů, které lze spustit.
+
+Dokumentace djangových příkazů je v `dokumentaci Djanga
+<https://docs.djangoproject.com/en/3.2/ref/django-admin/#available-commands>`_
+
+Ostatní užitečné příkazy
+^^^^^
+
+- ``git status`` je univerzální nápověda na aktuální stav repozitáře a co s tím
+  lze dělat.
+- ``git clean -fxd`` smaže všechny soubory, které nejsou uložené v gitu (včetně
+  ignorovaných). **Nebezpečný příkaz**, zamysli se, než ho spustíš
+
+Specifika lokálního webu
+-------
+
+Lokální uživatelé
+^^^^^^^
+
+Přihlašovací údaje jsou psány jako ``login:heslo``
+
+- Superuživatel: ``admin:admin``
+- Orgovské účty: ``o:o``, ``o1:o1`` až ``o3:o3``
+- Řešitelské účty: ``r:r``, ``r1:r1`` až ``r3:r3``
+
+Všechny tyto účty jsou (?) svázané s nějakými fiktivními osobami, není ale zřejmé se
+kterými, budeš to muset vyzkoušet a pak tady zdokumentovat :-)
+
+E-maily
+^^^^^
+
+Posílání e-mailů se lokálně dá zkoušet, e-mail se vypíše do terminálu, kde je
+web spuštěn (e.g. pomocí ``make/run``).
+
+Pruhy
+^^^^
+
+To, že má lokální web po stranách zelené pruhy je normální a správně, slouží to
+k vizuálnímu odlišení lokálního webu.
+
+.. TODO: Mít někde popis všech tří instancí a tady na něj pak odkázat.
+.. - Tahák k používání gitových větví: do workflow, ne sem…
+.. - Užitečné odkazy – kam se kouknout
+  (dohledávání views podle URL, settings_*, )
+.. - Zpříjemnění práce (ssh-klíče, tea, --help, …)
 
-Když si lokálně spustíte web, běží na http://127.0.0.1:8000/, admin najdete na http://127.0.0.1:8000/admin/ (admin/admin) Až skončíš s vývojem webu, spusť “deactivate”. Tím zmizí ‘(env)’ ze začátku promptu.

make/README.md

@@ -1,34 +1,2 @@
 Milý člověče, M&Mí web tě vítá. Prosím, neděs se, zkusím tě provést lokálním zprovozněním webu.
 
-Předně: většina příkazů bude asi vypisovat spoustu detailů, takže ti doporučuji
-si tento text otevřít někde separátně. Nachází se v repozitáři v
-`make/README.md`, případně si jej můžeš zobrazit hezčeji vykreslený na
-[Gitee](https://gitea.ks.matfyz.cz/mam/mamweb/src/branch/master/make/README.md).
-
-O zprovoznění webu se stará hlavně skript `make/install_web`. Ten vytvoří
-virtualenv (neexistuje-li) a nainstaluje do něj závislosti webu. Pak ovšem
-budeš potřebovat nahrát další data do databáze, což uděláš pomocí příkazů
-`./manage.py testdata` a `./manage.py loaddata data/*`. Skript
-`make/install_web` ti to kdyžtak připomene.
-
-Samotný web spustíš třeba pomocí `make/run`, nebo ekvivalentně `./manage.py runserver`.
-
-Pozor: zatímco skripty v `make/` to nepotřebují, pro použití skriptu
-`./manage.py` se potřebuješ přepnout do virtuálního prostředí. To uděláš velmi
-pravděpodobně spuštěním `source env/bin/activate`, před začátkem _promptu_ by
-se mělo objevit `(env)`. Pro opuštění spusť `deactivate`.
-
-Časté problémy
------
-Je možné, že nemáš všechny potřebné závislosti v systému. Proto je možné, že
-`make/install_web` vyhodí nějakou chybovou hlášku:
-
-- `Error: pg_config executable not found.`:  nainstaluj si `libpq-dev` (na Ubuntu/Debianu, jinde se příslušný balíček může jmenovat jinak)
-- Chybová hláška obsahuje `#include <Python.h>`: nainstaluj si `python3-dev`
-
-
-<!--
-FIXME: Protože tento soubor vypisujeme, tak nemůžeme zobrazit aktuální cestu
-venvu, takže tu kvůli tomu jsou hardcodované cesty. Asi by se mohl nějak
-generovat ze šablony, která má přístup k make/lib.sh, ale zatím to není implementované.
--->