From 5d6119069575b4383af41f6196b2582bf7b64d07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Mon, 14 Feb 2022 22:59:46 +0100 Subject: [PATCH] =?UTF-8?q?Dal=C5=A1=C3=ADch=20p=C3=A1r=20zm=C4=9Bn=20v=20?= =?UTF-8?q?dokumentaci?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/index.rst | 1 + docs/sphinx.rst | 42 ++++++++++++++++++++++++++---------------- docs/vyvoj.rst | 20 ++++++++++++++++++++ 3 files changed, 47 insertions(+), 16 deletions(-) create mode 100644 docs/vyvoj.rst diff --git a/docs/index.rst b/docs/index.rst index beedfa09..e64a5ff3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Vítejte v dokumentaci M&Mího webu! :caption: M&M web :maxdepth: 2 + vyvoj sphinx modules/modules diff --git a/docs/sphinx.rst b/docs/sphinx.rst index c4f3b7f7..dcf70ca7 100644 --- a/docs/sphinx.rst +++ b/docs/sphinx.rst @@ -1,30 +1,40 @@ -Sphinx -====== +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 ``doc``. -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). +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). Sphinx se píše v rst: `Návod na syntaxi rst`_ +.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections + Problém ------- -U mě ```make html``` vůbec nereagoval na změny ```Makefile```, tedy jsem ```sphinx-apidoc...``` nakódil přímo do ```conf.py```. +U mě ``make html`` vůbec nereagoval na změny ``Makefile``, tedy jsem ``sphinx-apidoc...`` nakódil přímo do ``conf.py``. make html --------- -Make html dělá následující: Vygenerují se rst soubory do modules z pythoní dokumentace pomocí: +Make html dělá následující: Vygenerují se rst soubory do modules z pythoní dokumentace pomocí:: -```sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f``` + sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f -- ```--module-first``` říká, že dokumentace modulu má být dřív než to, co obsahuje, -- ```-o``` je výstupní složka příkazu, -- ```..``` prochází složku mamweb, -- ```../*/migrations``` ignoruje migrace -- ```--templatedir _templates``` určuje templaty, podle kterých se vyrábí rst z Pythoní dokumentace a struktury složek a souborů, -- ```-f``` donutí phinx znovu přegenerovat soubory, protože nepozná, že se nějaká dokumentace změnila) +- ``--module-first`` říká, že dokumentace modulu má být dřív než to, co obsahuje, +- ``-o`` je výstupní složka příkazu, +- ``..`` prochází složku mamweb, +- ``../*/migrations`` ignoruje migrace +- ``--templatedir _templates`` určuje templaty, podle kterých se vyrábí rst z Pythoní dokumentace a struktury složek a souborů, +- ``-f`` donutí phinx znovu přegenerovat soubory, protože nepozná, že se nějaká dokumentace změnila) -Poté se spustí „samotný sphinx“ a vygenerují se soubory v ```_build/html```. +Poté se spustí „samotný sphinx“ a vygenerují se soubory v ``_build/html``. -.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections +Templates +--------- +Templaty jsou originální s pár změnami: + + - Změnil jsem nadpisy + - Odstranil jsem některá slova v nadpisech (module, package, …) + - Odstranil jsem nadpis Subpackages + +přišlo mi to takhle lepší. Ale stále nejsem moc spokojen, protože je to pořád nepřehledné. diff --git a/docs/vyvoj.rst b/docs/vyvoj.rst new file mode 100644 index 00000000..438e8199 --- /dev/null +++ b/docs/vyvoj.rst @@ -0,0 +1,20 @@ +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 + + ## 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 + +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. \ No newline at end of file