Browse Source

Dalších pár změn v dokumentaci

okenkove_obalky
Jonas Havelka 3 years ago
parent
commit
5d61190695
  1. 1
      docs/index.rst
  2. 42
      docs/sphinx.rst
  3. 20
      docs/vyvoj.rst

1
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

42
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é.

20
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.
Loading…
Cancel
Save