From ea582b6e14dfe2477aa6c559f2152dac9f174bb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= <jonas.havelka@volny.cz>
Date: Mon, 14 Feb 2022 22:30:44 +0100
Subject: [PATCH] =?UTF-8?q?Automatick=C3=A9=20p=C5=99egenerov=C3=A1n=C3=AD?=
 =?UTF-8?q?=20dokumentace=20a=20dal=C5=A1=C3=AD=20mal=C3=A9=20zm=C4=9Bny?=
 =?UTF-8?q?=20v=20dokumentaci=20pomoc=C3=AD=20sphinxu?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Makefile             |  1 +
 docs/_templates/toc.rst_t |  2 +-
 docs/conf.py              |  6 +++++-
 docs/sphinx.rst           | 22 ++++++++++++++++++++--
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index d4bb2cbb..61eab5c7 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,4 +17,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	#sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t
index 611dc7fa..d519d988 100644
--- a/docs/_templates/toc.rst_t
+++ b/docs/_templates/toc.rst_t
@@ -1,4 +1,4 @@
-{{ "Aplikace:" | heading }}
+{{ "Seznam aplikací" | heading }}
 
 .. toctree::
    :maxdepth: {{ maxdepth }}
diff --git a/docs/conf.py b/docs/conf.py
index 10a14da6..80f0846c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,6 +32,7 @@ author = 'Orgové'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -64,4 +65,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
\ No newline at end of file
+html_static_path = ['_static']
+
+from sphinx.ext.apidoc import main
+main(['--module-first', '-o', "modules", "..", "../*/migrations", "--templatedir", "_templates", '-f'])
\ No newline at end of file
diff --git a/docs/sphinx.rst b/docs/sphinx.rst
index f19557a5..c4f3b7f7 100644
--- a/docs/sphinx.rst
+++ b/docs/sphinx.rst
@@ -1,12 +1,30 @@
 Sphinx
 ======
 
-```sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates```
+Dokumentace se zkompiluje příkazem ```make html``` ve složce ```doc```.
 
-`Návod na syntaxi rst`_
+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`_
 
+Problém
+-------
+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í:
 
+```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)
+
+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