From 3789836291761691c8b82bd25d71d2e54c625727 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Mon, 31 Jan 2022 21:59:29 +0100 Subject: [PATCH 1/9] Sphinx init --- docs/Makefile | 20 +++++++++++++++ docs/conf.py | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 20 +++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++ requirements.txt | 4 +++ 5 files changed, 142 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..2df57310 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,63 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import django +sys.path.insert(0, os.path.abspath('..')) +os.environ['DJANGO_SETTINGS_MODULE'] = 'mamweb.settings' +django.setup() + + +# -- Project information ----------------------------------------------------- + +project = 'Web M&M' +copyright = '2022, Orgové' +author = 'Orgové' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'cs' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# 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 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..d60fc32b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. Web M&M documentation master file, created by + sphinx-quickstart on Mon Jan 31 21:56:04 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Vítejte v dokumentaci M&Mího webu! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Rejstříky a vyhledávání +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..8084272b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/requirements.txt b/requirements.txt index c447090d..c79a7580 100644 --- a/requirements.txt +++ b/requirements.txt @@ -57,3 +57,7 @@ uWSGI # Potřeba pro test data lorem + +# pro dokumentaci + +sphinx From 39c9eea11c3ade64bd72aa5d86da03f9056709fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Tue, 1 Feb 2022 00:42:01 +0100 Subject: [PATCH 2/9] =?UTF-8?q?Sphinx=20lep=C5=A1=C3=AD=20vzhled?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conf.py | 6 +++++- requirements.txt | 1 + 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 2df57310..10a14da6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,7 +55,11 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +import sphinx_rtd_theme + +html_theme = 'sphinx_rtd_theme' + +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, diff --git a/requirements.txt b/requirements.txt index c79a7580..9ad24a7f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -61,3 +61,4 @@ lorem # pro dokumentaci sphinx +sphinx_rtd_theme From 6b3fb8f19caaf0437a1ef612576364a4a27e78c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Tue, 1 Feb 2022 00:42:56 +0100 Subject: [PATCH 3/9] =?UTF-8?q?P=C3=A1r=20prvn=C3=ADch=20pokus=C5=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 4 +++ docs/_templates/module.rst_t | 8 +++++ docs/_templates/package.rst_t | 57 +++++++++++++++++++++++++++++++++++ docs/_templates/toc.rst_t | 7 +++++ docs/index.rst | 5 ++- docs/sphinx.rst | 12 ++++++++ 6 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/_templates/module.rst_t create mode 100644 docs/_templates/package.rst_t create mode 100644 docs/_templates/toc.rst_t create mode 100644 docs/sphinx.rst diff --git a/.gitignore b/.gitignore index 2e79367e..d3a2a533 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,7 @@ TODO # pro lidi, co programují v nástrojích od JetBrains .idea + +# dokumentace +docs/_build +docs/modules \ No newline at end of file diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t new file mode 100644 index 00000000..8a0a3556 --- /dev/null +++ b/docs/_templates/module.rst_t @@ -0,0 +1,8 @@ +{%- if show_headings %} +{{- [basename, ".py"] | join('') | e | heading }} + +{% endif -%} +.. automodule:: {{ qualname }} +{%- for option in automodule_options %} + :{{ option }}: +{%- endfor %} diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t new file mode 100644 index 00000000..809ced67 --- /dev/null +++ b/docs/_templates/package.rst_t @@ -0,0 +1,57 @@ +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- pkgname | e | heading }} +{% else %} +{{- pkgname | e | heading }} +{% endif %} + +{%- if is_namespace %} +.. py:module:: {{ pkgname }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +{# Subpackages #} +{# ----------- #} + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +{# Submodules #} +{# ---------- #} +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- submodule | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +{%- if not modulefirst and not is_namespace %} +Module contents +--------------- + +{{ automodule(pkgname, automodule_options) }} +{% endif %} \ No newline at end of file diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t new file mode 100644 index 00000000..611dc7fa --- /dev/null +++ b/docs/_templates/toc.rst_t @@ -0,0 +1,7 @@ +{{ "Aplikace:" | heading }} + +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index d60fc32b..beedfa09 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,8 +7,11 @@ Vítejte v dokumentaci M&Mího webu! =================================== .. toctree:: + :caption: M&M web :maxdepth: 2 - :caption: Contents: + + sphinx + modules/modules diff --git a/docs/sphinx.rst b/docs/sphinx.rst new file mode 100644 index 00000000..f19557a5 --- /dev/null +++ b/docs/sphinx.rst @@ -0,0 +1,12 @@ +Sphinx +====== + +```sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates``` + +`Návod na syntaxi rst`_ + + + + + +.. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections From ea582b6e14dfe2477aa6c559f2152dac9f174bb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Mon, 14 Feb 2022 22:30:44 +0100 Subject: [PATCH 4/9] =?UTF-8?q?Automatick=C3=A9=20p=C5=99egenerov=C3=A1n?= =?UTF-8?q?=C3=AD=20dokumentace=20a=20dal=C5=A1=C3=AD=20mal=C3=A9=20zm?= =?UTF-8?q?=C4=9Bny=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 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 5/9] =?UTF-8?q?Dal=C5=A1=C3=ADch=20p=C3=A1r=20zm=C4=9Bn=20?= =?UTF-8?q?v=20dokumentaci?= 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 From cbf17f77090bc7f5ad20b0aa4774b027405e9b64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Tue, 15 Feb 2022 17:45:52 +0100 Subject: [PATCH 6/9] =?UTF-8?q?Dal=C5=A1=C3=AD=20konfigurace=20sphinx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conf.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 80f0846c..584272c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,8 @@ author = 'Orgové' extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. @@ -67,5 +69,17 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +# Provázání s jinými dokumentacemi +intersphinx_mapping = {'python': ('https://docs.python.org/3', None), + 'django': ('http://docs.djangoproject.com/en/3.2/', + 'http://docs.djangoproject.com/en/3.2/_objects/'),} + +# Generování tříd/funkcí/atributů v pořádí jak jsou naprogramované +autodoc_member_order = "bysource" + +# Nezobrazování zděděné (ze super tříd) dokumentace TODO nefunguje? +autodoc_inherit_docstrings = False + +# Spouštění sphinx-apidoc from sphinx.ext.apidoc import main main(['--module-first', '-o', "modules", "..", "../*/migrations", "--templatedir", "_templates", '-f']) \ No newline at end of file From 5113a7adab9f4a85657729fb4bb6e64620ede77e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Tue, 15 Feb 2022 17:48:16 +0100 Subject: [PATCH 7/9] =?UTF-8?q?Prvn=C3=AD=20dokumentace?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aesop/apps.py | 3 + aesop/urls.py | 7 +++ aesop/views.py | 5 ++ api/apps.py | 3 + api/urls.py | 12 ++++ api/views/__init__.py | 5 ++ api/views/autocomplete.py | 6 ++ api/views/exports.py | 3 + api/views/helpers.py | 3 + docs/dalsi_soubory.rst | 92 ++++++++++++++++++++++++++++++ docs/default_doc.rst | 55 ++++++++++++++++++ docs/index.rst | 1 + docs/sphinx.rst | 3 +- galerie/urls.py | 9 ++- header_fotky/__init__.py | 6 ++ header_fotky/admin.py | 15 +++++ header_fotky/apps.py | 3 + header_fotky/context_processors.py | 16 +++++- header_fotky/models.py | 28 ++++++++- korektury/__init__.py | 5 ++ korektury/admin.py | 21 +++++++ korektury/forms.py | 11 ++++ korektury/models.py | 16 +++++- korektury/testutils.py | 4 ++ korektury/urls.py | 8 +++ korektury/views.py | 6 +- mamweb/admin.py | 5 ++ mamweb/urls.py | 17 ++++++ odevzdavatko/admin.py | 6 ++ odevzdavatko/apps.py | 3 + odevzdavatko/urls.py | 14 +++++ personalni/apps.py | 3 + personalni/urls.py | 14 +++++ prednasky/urls.py | 9 +++ seminar/__init__.py | 6 ++ seminar/urls.py | 34 ++++++++++- soustredeni/apps.py | 3 + treenode/apps.py | 3 + treenode/urls.py | 5 ++ various/apps.py | 3 + various/autentizace/urls.py | 13 +++++ vysledkovky/apps.py | 3 + 42 files changed, 479 insertions(+), 8 deletions(-) create mode 100644 docs/dalsi_soubory.rst create mode 100644 docs/default_doc.rst diff --git a/aesop/apps.py b/aesop/apps.py index c2d509f1..4e8b4787 100644 --- a/aesop/apps.py +++ b/aesop/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/aesop/urls.py b/aesop/urls.py index f39a0ba8..946a873b 100644 --- a/aesop/urls.py +++ b/aesop/urls.py @@ -1,3 +1,10 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``aesop-export/mam-rocnik-.csv`` (seminar_export_rocnik) :class:`~aesop.views.ExportRocnikView` +- ``aesop-export/mam-sous-.csv`` (seminar_export_sous) :class:`~aesop.views.ExportSousView` +- ``aesop-export/index.csv`` (seminar_export_index) :class:`~aesop.views.ExportIndexView` +""" from django.urls import path from aesop import views diff --git a/aesop/views.py b/aesop/views.py index d815b5d5..4d1748b7 100644 --- a/aesop/views.py +++ b/aesop/views.py @@ -1,3 +1,8 @@ +""" +Soubor sloužící k deklaraci jednotlivých „views“ (nejčastěji funkce beroucí request +a vracející :func:`django.shortcuts.render` respektive nějakou response, nebo +třídy většinou rozšiřující nějakou třídu z :mod:`django.views.generic`) +""" import django from django.shortcuts import get_object_or_404 from django.http import HttpResponse diff --git a/api/apps.py b/api/apps.py index d87006dd..6a2bdbc4 100644 --- a/api/apps.py +++ b/api/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/api/urls.py b/api/urls.py index e869df80..23aafe36 100644 --- a/api/urls.py +++ b/api/urls.py @@ -1,3 +1,15 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``api/expor/skoly/`` (export_skoly) :func:`~api.views.exports.exportSkolView` +- ``api/autocomplete/skola/`` (autocomplete_skola) :class:`~api.views.autocomplete.SkolaAutocomplete` +- ``api/autocomplete/resitel/`` (autocomplete_resitel) :class:`~api.views.autocomplete.ResitelAutocomplete` +- ``api/autocomplete/problem/odevzdatelny`` (autocomplete_problem_odevzdatelny) :class:`~api.views.autocomplete.OdevzdatelnyProblemAutocomplete` + +Na autocomplete v3 čeká: + +- ``autocomplete/organizatori/`` (seminar_autocomplete_organizator) :class:`~api.views.autocomplete.OrganizatorAutocomplete` +""" from django.urls import path from . import views from seminar.utils import org_required diff --git a/api/views/__init__.py b/api/views/__init__.py index fc00554e..13ce91ba 100644 --- a/api/views/__init__.py +++ b/api/views/__init__.py @@ -1,2 +1,7 @@ +""" +Soubory sloužící k deklaraci jednotlivých „views“ (nejčastěji funkce beroucí request +a vracející :func:`django.shortcuts.render` respektive nějakou response, nebo +třídy většinou rozšiřující nějakou třídu z :mod:`django.views.generic`) +""" from .autocomplete import * from .exports import * diff --git a/api/views/autocomplete.py b/api/views/autocomplete.py index 630e9106..217df008 100644 --- a/api/views/autocomplete.py +++ b/api/views/autocomplete.py @@ -1,3 +1,6 @@ +""" + Views k :mod:`dal.autocomplete` pro vyhledávání objektů nějaké třídy v databázi. +""" from dal import autocomplete from django.shortcuts import get_object_or_404 from django.db.models import Q @@ -7,6 +10,7 @@ from .helpers import LoginRequiredAjaxMixin # TODO filosofie - zkratky, jak v databázi, tak ve vyhledávání (SPŠE, GASOŠ, Kpt., soukr) class SkolaAutocomplete(autocomplete.Select2QuerySetView): + """ View k :mod:`dal.autocomplete` pro vyhledávání škol hlavně při registraci. """ def get_queryset(self): # Don't forget to filter out results depending on the visitor ! qs = m.Skola.objects.all() @@ -25,6 +29,7 @@ class SkolaAutocomplete(autocomplete.Select2QuerySetView): return qs class ResitelAutocomplete(LoginRequiredAjaxMixin,autocomplete.Select2QuerySetView): + """ View k :mod:`dal.autocomplete` pro vyhledávání řešitelů především v odevzdávátku. """ def get_queryset(self): qs = m.Resitel.objects.all() if self.q: @@ -40,6 +45,7 @@ class ResitelAutocomplete(LoginRequiredAjaxMixin,autocomplete.Select2QuerySetVie return qs class OdevzdatelnyProblemAutocomplete(autocomplete.Select2QuerySetView): + """ View k :mod:`dal.autocomplete` pro vyhledávání problémů především v odevzdávátku. """ def get_queryset(self): nastaveni = get_object_or_404(m.Nastaveni) rocnik = nastaveni.aktualni_rocnik diff --git a/api/views/exports.py b/api/views/exports.py index 6df7d32b..5c1d57af 100644 --- a/api/views/exports.py +++ b/api/views/exports.py @@ -2,6 +2,9 @@ import seminar.models as m from django.core import serializers as ser from django.http import HttpResponse def exportSkolView(request): + """ + „view“, který vrací json se seznamem škol, u kterých je uvedeno: 'id', 'izo', 'nazev', 'kratky_nazev', 'ulice', 'mesto', 'psc', 'stat', 'je_zs', 'je_ss' + """ # Některé fieldy nechceme: Kontaktní osoby, AESOP ID, org poznámky. fields = ('id', 'izo', 'nazev', 'kratky_nazev', 'ulice', 'mesto', 'psc', 'stat', 'je_zs', 'je_ss') # TODO: Použít JSONL, aby protistrana mohla číst po řádkách a nesežralo to tunu paměti úplně hned diff --git a/api/views/helpers.py b/api/views/helpers.py index 652344bc..cecbb53f 100644 --- a/api/views/helpers.py +++ b/api/views/helpers.py @@ -2,6 +2,9 @@ from django.http import JsonResponse class LoginRequiredAjaxMixin(object): + """ + Objekt přidávající povinnost být přihlášený k zobrazení daného view. + """ def dispatch(self, request, *args, **kwargs): #if request.is_ajax() and not request.user.is_authenticated: # Pokud to otevřu jako stránku, tak se omezení neuplatní, takže to asi nechceme if not request.user.is_authenticated: diff --git a/docs/dalsi_soubory.rst b/docs/dalsi_soubory.rst new file mode 100644 index 00000000..1a59ee15 --- /dev/null +++ b/docs/dalsi_soubory.rst @@ -0,0 +1,92 @@ +Další soubory/složky v kořenovém adresáři +========================================= + +media +----- +Složka, kam django nahrává soubory „jako by je nahrávalo do databáze“. + +static +------ +Složka, kam django nakopíruje všechno ze složek static a pak na to z templatů / kódu jde ukazovat pomocí ``static``. + +_git_hooks +---------- +Hooky do gitu pro kontrolu Pythoního stylu. Především ``flake8``. + +Zbylo tu z minulosti mamwebu. + +data +---- +Obsahuje data, která patří do databáze, ale jsou přímo součástí webu jako +takového. Aktuálně jsou to statické stránky, meníčko a rozložení obrázků +v pozadí meníčka. + +Generuje se za pomocí:: + + ./manage.py dumpdata flatpages > data/flat_new.json + ./fix_json.py data/flat_new.json data/flat.json + +nebo (v případě meníčka):: + + ./manage.py dumpdata sitetree --natrual-foreign > data/sitetree_new.json + ./fix_json.py data/sitetree_new.json data/sitetree.json + +deploy_v2 +--------- +Věci, které byly potřeba při nasazování nového (2021) webu. + +docs +---- +Zde je dokumentace webu. Viz :ref:`Sphinx na našem webu`. + +setup +----- +Tato složka obsahuje různé konfiguráky potřebné k rozběhnutí webu na serveru. + +vue_frontend +------------ +Obsahuje první pokusy o editory treenodů ve vue. + +.gitignore +---------- +Klasické `.gitignore`_ + +.. _.gitignore: https://git-scm.com/docs/gitignore + +checklinks.sh +------------- +„Týrací“ skript na kontrolu, že nic, kam se lze proklikat na webu, nehází chybu. + +constraints.txt +--------------- +Obsahuje omezení na :ref:`requirements.txt`. + +convert_spaces_to_tabs.sh +------------------------- +Skript na změnu odsazování. + +db-local.sqlite3 +---------------- +Lokální databáze (na serveru není). + +diff_db_backup.sh +----------------- +Nevím. Typoval bych skript na diff záloh (resp. dumpů) databáze. + +Makefile +-------- +Klasické `Makefile`_. Obsahuje například vytvoření virtual_env, instalaci a nasazování webu. + +.. _Makefile: https://www.gnu.org/software/make/manual/make.html + +manage.py +--------- +Základní soubor djanga. + +README.md +--------- +Většina je spíš zbytek po bývalých webařích. + +requirements.txt +---------------- +Seznam balíčků, které jsou potřeba pro běh mamwebu. (Cílem je vytvoření virtualenvu se všemi těmito balíčky, např. pomocí daného příkazu v :ref:`Makefile`.) diff --git a/docs/default_doc.rst b/docs/default_doc.rst new file mode 100644 index 00000000..9175d632 --- /dev/null +++ b/docs/default_doc.rst @@ -0,0 +1,55 @@ +Defaultní dokumentace speciálních souborů +========================================= + +Drobná nápověda k běžným django souborům. (Do nich jsem to vkládal copy-paste.) + +admin.py +-------- +Soubor sloužící k definici toho, co bude v adminu. Většinou pouhým zavoláním +funkce :func:`django.contrib.admin.site.register`, v případě, že chceme něco +upravit, tak jako třída rozšiřující :class:`django.contrib.admin.ModelAdmin` +s dekorátorem :func:`django.contrib.admin.register`. + +Zde se definuje admin pro: + +apps.py +------- +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. + +forms.py +-------- +Formuláře (:class:`django.forms.Form`) umožňují jednoduchou tvorbu formulářů, +které lze pak jednoduše dát do frontendu i zpracovat na backendu. + +Pro přidání políčka do formuláře je potřeba + - mít v modelu tu položku, kterou chci upravovat + - přidat do views (prihlaskaView, resitelEditView) + - přidat do forms + - includovat do html + +models.py +--------- +Tento soubor slouží k definici databázového modelu. + +Třídy rozšiřují většinou :class:`django.db.models.Model` a jejich atributy jsou +většinou sloupce v databázi (tj. nastaví se na hodnotu něčeho z :mod:`django.db.models`). +Na výběr jsou: + + - :class:`django.db.models.TextField` + - :class:`django.db.models.ForeignKey` + - :class:`django.db.models.DateField` + - :class:`django.db.models.DateTimeField` + - :class:`django.db.models.ImageField` + - :class:`django.db.models.CharField` + +testutils.py +------------ +Soubor sloužící ke generování testdat. + +urls.py +------- +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +views.py +-------- + diff --git a/docs/index.rst b/docs/index.rst index e64a5ff3..0f779e42 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Vítejte v dokumentaci M&Mího webu! vyvoj sphinx + dalsi_soubory modules/modules diff --git a/docs/sphinx.rst b/docs/sphinx.rst index dcf70ca7..99a92d74 100644 --- a/docs/sphinx.rst +++ b/docs/sphinx.rst @@ -6,9 +6,10 @@ 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). -Sphinx se píše v rst: `Návod na syntaxi rst`_ +Sphinx se píše v rst: `Návod na syntaxi rst`_ `Cheat sheet`_ .. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections +.. _Cheat sheet: https://sphinx-tutorial.readthedocs.io/cheatsheet/ Problém ------- diff --git a/galerie/urls.py b/galerie/urls.py index d299165f..2e311cd8 100644 --- a/galerie/urls.py +++ b/galerie/urls.py @@ -1,5 +1,12 @@ -# coding: utf-8 +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: +- ``/`` :func:`~galerie.views.nahled` +- ``//`` :func:`~galerie.views.detail` +- ``/new/`` :func:`~galerie.views.new_galerie` +- ``/plus//`` :func:`~galerie.views.plus_galerie` +- ``/minus//`` :func:`~galerie.views.minus_galerie` +""" from django.urls import path from seminar.utils import org_required from . import views diff --git a/header_fotky/__init__.py b/header_fotky/__init__.py index e69de29b..6ba2ea0d 100644 --- a/header_fotky/__init__.py +++ b/header_fotky/__init__.py @@ -0,0 +1,6 @@ +""" +Aplikace umožňující „na uživatelské úrovni“ měnit obrázek v pozadí meníčka. + +Umožňuje uložit obrázek a následně popsat, na kterých stránkách (podle url) +a v který čas (den/noc) se má zobrazovat. +""" \ No newline at end of file diff --git a/header_fotky/admin.py b/header_fotky/admin.py index 35d3427b..b939541b 100644 --- a/header_fotky/admin.py +++ b/header_fotky/admin.py @@ -1,9 +1,24 @@ +""" +Soubor sloužící k definici toho, co bude v adminu. Většinou pouhým zavoláním +funkce :func:`django.contrib.admin.site.register`, v případě, že chceme něco +upravit, tak jako třída rozšiřující :class:`django.contrib.admin.ModelAdmin` +s dekorátorem :func:`django.contrib.admin.register`. + +Zde se definuje admin pro: + +- :class:`~header_fotky.models.FotkaHeader` +- :class:`~header_fotky.models.FotkaUrlVazba` +""" from django.contrib import admin from django.contrib.admin import ModelAdmin import header_fotky.models as m class FotkaPozadiAdmin(ModelAdmin): + """ + Nastaví čas vložení (:attr:`~header_fotky.models.FotkaHeader.cas`) jako + readonly = neměnitelný + """ readonly_fields = ['cas'] admin.site.register(m.FotkaHeader, FotkaPozadiAdmin) diff --git a/header_fotky/apps.py b/header_fotky/apps.py index 084aa955..13f93ed4 100644 --- a/header_fotky/apps.py +++ b/header_fotky/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/header_fotky/context_processors.py b/header_fotky/context_processors.py index be259cbf..0040cb5f 100644 --- a/header_fotky/context_processors.py +++ b/header_fotky/context_processors.py @@ -1,4 +1,8 @@ - +""" +Context processory lze přidat do djanga v :mod:`~mamweb.settings` a dělají to, +že do contextu (tj. to, z čeho se např. berou proměnné v templatech) libovolné +stránky přidají další věci. +""" from datetime import datetime, date import random @@ -8,7 +12,15 @@ from header_fotky.models import FotkaUrlVazba def vzhled(request): - ''' Podle casu prida do templatu, zdali je nebo neni noc ''' + """ + Podle času přidá do contextu, zdali je nebo není noc. Dále podle dení + doby a url přidá do contextu správnou fotku. + + url adresu nejprve vyzkouší celou, pak postupně odřezává věci za + lomítkem, dokud nenajde url, pro kterou existuje alespoň jedna fotka. + Z fotek pro toto url zkusí vybrat tu ve správné denní době a až poté + libovolnou. (Z více možných fotek pro 1 url a 1 dobu vybírá náhodně.) + """ hodin = datetime.now().hour if (hodin <= 6) or (hodin >= 20): noc = True diff --git a/header_fotky/models.py b/header_fotky/models.py index 481a652c..750cc575 100644 --- a/header_fotky/models.py +++ b/header_fotky/models.py @@ -1,9 +1,24 @@ +""" +Tento soubor slouží k definici databázového modelu. + +Třídy rozšiřují většinou :class:`django.db.models.Model` a jejich atributy jsou +většinou sloupce v databázi (tj. nastaví se na hodnotu něčeho z :mod:`django.db.models`). +Na výběr jsou: + + - :class:`django.db.models.TextField` + - :class:`django.db.models.ForeignKey` + - :class:`django.db.models.DateField` + - :class:`django.db.models.DateTimeField` + - :class:`django.db.models.ImageField` + - :class:`django.db.models.CharField` +""" from django.core.exceptions import ValidationError from django.db import models from django.utils import timezone class FotkaHeader(models.Model): + """ fotka pro :mod:`fotka_header`, konkrétně :class:`~fotka_header.models.FotkaUrlVazba` """ class Meta: ordering = ['-cas'] db_table = 'fotky_header' @@ -11,27 +26,34 @@ class FotkaHeader(models.Model): verbose_name_plural = u'fotky do pozadí menu' cas = models.DateTimeField(u'čas vložení fotky', default=timezone.now, help_text='Čas vložení fotky') + """ čas vložení fotky """ nazev = models.CharField( u'název fotky', null=False, blank=False, unique=True, primary_key=True, max_length=50, help_text='Název např. archiv_noc' ) + """ jméno fotky na webu """ fotka = models.ImageField(upload_to='header', null=False, blank=False) + """ soubor fotky (Nahrává se automaticky do složky ``media``.) """ def __str__(self): return self.nazev def clean(self): + """ kontroluje, zda sedí poměr stran """ if not self.fotka: raise ValidationError("Chybí obrázek") - """ Kontroluje, zda sedí poměr stran """ if abs(self.fotka.width - (self.fotka.height * 970 / 350)) > 2: raise ValidationError("Obrázek by měl mít rozměry 970w na 350h, nebo alespoň podobný poměr stran.") super().clean() class FotkaUrlVazba(models.Model): + """ + spojení :class:`~fotka_header.models.FotkaHeader` a url + (resp. „prefixu“ url), na které má být zobrazována + """ class Meta: ordering = ['url'] db_table = 'fotky_url_vazby' @@ -42,11 +64,13 @@ class FotkaUrlVazba(models.Model): u'URL', blank=True, null=False, max_length=100, help_text='url prefix stránek např: /archiv/ nebo /' ) + """ url prefix stránek, kde má být fotka zobrazena, např: /archiv/ nebo / """ fotka = models.ForeignKey( FotkaHeader, blank=False, null=False, verbose_name='fotka', on_delete=models.CASCADE ) + """ :class:`~fotka_header.models.FotkaHeader`, která má být zobrazována """ DOBA_DEN = 'den' DOBA_NOC = 'noc' @@ -57,9 +81,11 @@ class FotkaUrlVazba(models.Model): (DOBA_OBOJI, 'Zobrazovat pořád')] denni_doba = models.CharField('denní doba', max_length=16, choices=DOBA_CHOICES, blank=False, default=DOBA_OBOJI) + """ dení doba, kdy tam má být zobrazována """ def __str__(self): return self.url def url_fotky(self): + """ vrací url fotky (tj. url, kde reálně získám soubor fotky) """ return self.fotka.fotka.url diff --git a/korektury/__init__.py b/korektury/__init__.py index e69de29b..811204aa 100644 --- a/korektury/__init__.py +++ b/korektury/__init__.py @@ -0,0 +1,5 @@ +""" + Seznam pdf k opravě a `opraf`_ v djangu místo PHP. + + .. _opraf: https://github.com/vitstradal/opraf +""" \ No newline at end of file diff --git a/korektury/admin.py b/korektury/admin.py index 64b2032f..2e91ae75 100644 --- a/korektury/admin.py +++ b/korektury/admin.py @@ -1,3 +1,13 @@ +""" +Soubor sloužící k definici toho, co bude v adminu. Většinou pouhým zavoláním +funkce :func:`django.contrib.admin.site.register`, v případě, že chceme něco +upravit, tak jako třída rozšiřující :class:`django.contrib.admin.ModelAdmin` +s dekorátorem :func:`django.contrib.admin.register`. + +Zde se definuje admin pro: + +- :class:`korektury.models.KorekturovanePDF` +""" from django.contrib import admin from reversion.admin import VersionAdmin from korektury.models import KorekturovanePDF @@ -7,10 +17,18 @@ from django.urls import reverse # Register your models here. class KorekturovanePDFAdmin(VersionAdmin): + """ + nastaví čas vložení (:attr:`~koretkury.models.KorekturovanePDF.cas`) a počet + stran (:attr:`~koretkury.models.KorekturovanePDF.stran`) jako readonly = + neměnitelný + + Při prvním uložení pošle e-mail. + """ readonly_fields = ['cas', 'stran'] def get_readonly_fields(self, request, obj=None): + """ Nevím, proč to tu je - Jidáš """ if obj: return self.readonly_fields + ['pdf'] return self.readonly_fields @@ -26,6 +44,9 @@ class KorekturovanePDFAdmin(VersionAdmin): search_fields = [] def save_model(self, request, obj, form, change): + """ + Pokud je soubor nový a má se poslat e-mail, tak pošle e-mail o novém pdf. + """ super().save_model(request, obj, form, change) if not change and obj.poslat_mail: # Je nový a má se poslat mail odkaz = request.build_absolute_uri(reverse('korektury', kwargs={'pdf': obj.id})) diff --git a/korektury/forms.py b/korektury/forms.py index 7385e687..2fd439a6 100644 --- a/korektury/forms.py +++ b/korektury/forms.py @@ -1,6 +1,17 @@ +""" +Formuláře (:class:`django.forms.Form`) umožňují jednoduchou tvorbu formulářů, +které lze pak jednoduše dát do frontendu i zpracovat na backendu. + +Pro přidání políčka do formuláře je potřeba + - mít v modelu tu položku, kterou chci upravovat + - přidat do views (prihlaskaView, resitelEditView) + - přidat do forms + - includovat do html +""" from django import forms class OpravaForm(forms.Form): + """ formulář k přidání opravy (:class:`korektury.models.Oprava`) """ text = forms.CharField(max_length=256) autor = forms.CharField(max_length=20) x = forms.IntegerField() diff --git a/korektury/models.py b/korektury/models.py index 240323a8..6cef59bc 100644 --- a/korektury/models.py +++ b/korektury/models.py @@ -1,4 +1,17 @@ -# -*- coding: utf-8 -*- +""" +Tento soubor slouží k definici databázového modelu. + +Třídy rozšiřují většinou :class:`django.db.models.Model` a jejich atributy jsou +většinou sloupce v databázi (tj. nastaví se na hodnotu něčeho z :mod:`django.db.models`). +Na výběr jsou: + + - :class:`django.db.models.TextField` + - :class:`django.db.models.ForeignKey` + - :class:`django.db.models.DateField` + - :class:`django.db.models.DateTimeField` + - :class:`django.db.models.ImageField` + - :class:`django.db.models.CharField` +""" import os from django.db import models from django.utils import timezone @@ -16,6 +29,7 @@ from unidecode import unidecode def generate_filename(self, filename): + """ vyrobí jméno souboru podle původního jména a času nahrátí """ clean = get_valid_filename( unidecode( filename.replace('/', '-').replace('\0', '').replace(":", "_") diff --git a/korektury/testutils.py b/korektury/testutils.py index 5e75173e..5664982b 100644 --- a/korektury/testutils.py +++ b/korektury/testutils.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící ke generování testdat. +""" import logging import os from shutil import copyfile, rmtree @@ -11,6 +14,7 @@ logger = logging.getLogger(__name__) @transaction.atomic def create_test_pdf(rnd, organizatori): + """ Vyrobí testovací pdf ke korekturování. Nevyrábí korektury! """ logger.info('Vyrábím testovací pdf ke korekturovani') try: testpdfs = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'testpdfs') diff --git a/korektury/urls.py b/korektury/urls.py index dcd1d965..96eb4dd4 100644 --- a/korektury/urls.py +++ b/korektury/urls.py @@ -1,3 +1,11 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``korektury/`` (korektury_list) :class:`~korektury.views.KorekturySeskupeneListView` +- ``korektury/neseskupene/`` (korektury_neseskupene_list) :class:`~korektury.views.KorekturyAktualniListView` +- ``korektury/zastarale/`` (korektury_stare_list) :class:`~korektury.views.KorekturyZastaraleListView` +- ``korektury//`` (korektury) :class:`~korektury.views.KorekturyView` +""" from django.urls import path from seminar.utils import org_required from . import views diff --git a/korektury/views.py b/korektury/views.py index 97a34dbf..76f28ec8 100644 --- a/korektury/views.py +++ b/korektury/views.py @@ -1,4 +1,8 @@ -# -*- coding: utf-8 -*- +""" +Soubor sloužící k deklaraci jednotlivých „views“ (nejčastěji funkce beroucí request +a vracející :func:`django.shortcuts.render` respektive nějakou response, nebo +třídy většinou rozšiřující nějakou třídu z :mod:`django.views.generic`) +""" from django.shortcuts import get_object_or_404, render from django.views import generic from django.utils.translation import ugettext as _ diff --git a/mamweb/admin.py b/mamweb/admin.py index 9c421309..2ad1aaaa 100644 --- a/mamweb/admin.py +++ b/mamweb/admin.py @@ -1,3 +1,8 @@ +""" +Soubor sloužící k úpravě základních vlastností adminu. Zde se do adminu přidává +CKEditor, nastavuje české řazení v adminu a preference (zobrazuje se v seznamu +jako první) adminu k Semináři. +""" import locale from django.contrib import admin from django.contrib.admin import AdminSite diff --git a/mamweb/urls.py b/mamweb/urls.py index e91c0b17..3577c4f7 100644 --- a/mamweb/urls.py +++ b/mamweb/urls.py @@ -1,3 +1,20 @@ +""" +Soubor sloužící jako základní „router“, tj. zde se includují veškeré ostatní urls: + +- ``admin/`` :mod:`django.contrib.admin.site.urls` +- ``ckeditor/`` :mod:`ckeditor_uploader.urls` +- :mod:`seminar.urls` +- :mod:`odevzdavatko.urls` +- :mod:`korektury.urls` +- :mod:`prednasky.urls` +- :mod:`soustredeni.urls` +- :mod:`personalni.urls` +- :mod:`various.autentizace.urls` +- :mod:`api.urls` +- :mod:`treenode.urls` +- :mod:`aesop.urls` +- ``comments_dj/`` :mod:`django_comments.urls` +""" from django.urls import path, include from django.contrib.staticfiles.urls import staticfiles_urlpatterns from django.contrib import admin diff --git a/odevzdavatko/admin.py b/odevzdavatko/admin.py index 6048eb36..168beab1 100644 --- a/odevzdavatko/admin.py +++ b/odevzdavatko/admin.py @@ -1,3 +1,9 @@ +""" +Soubor sloužící k definici toho, co bude v adminu. Většinou pouhým zavoláním +funkce :func:`django.contrib.admin.site.register`, v případě, že chceme něco +upravit, tak jako třída rozšiřující :class:`django.contrib.admin.ModelAdmin` +s dekorátorem :func:`django.contrib.admin.register`. +""" from django.contrib import admin from django_reverse_admin import ReverseModelAdmin import seminar.models as m diff --git a/odevzdavatko/apps.py b/odevzdavatko/apps.py index 507c284f..95811247 100644 --- a/odevzdavatko/apps.py +++ b/odevzdavatko/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/odevzdavatko/urls.py b/odevzdavatko/urls.py index bb04f06a..e15b3807 100644 --- a/odevzdavatko/urls.py +++ b/odevzdavatko/urls.py @@ -1,3 +1,17 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``org/add_solution`` (seminar_vloz_reseni) :class:`~odevzdavatko.views.PosliReseniView` +- ``resitel/nahraj_reseni`` (seminar_nahraj_reseni) :class:`~odevzdavatko.views.NahrajReseniView` +- ``resitel/odevzdana_reseni/`` (seminar_resitel_odevzdana_reseni) :class:`~odevzdavatko.views.PrehledOdevzdanychReseni` +- ``org/reseni/`` (odevzdavatko_tabulka) :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``org/reseni/rocnik//`` (odevzdavatko_tabulka) :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``org/reseni///`` (odevzdavatko_reseni_resitele_k_problemu) :class:`~odevzdavatko.views.ReseniProblemuView` +- ``org/reseni//`` (odevzdavatko_detail_reseni) :func:`~seminar.utils.viewMethodSwitch` + :class:`~odevzdavatko.views.DetailReseniView` + :func:`~odevzdavatko.views.hodnoceniReseniView` +- ``org/reseni/all`` :class:`~odevzdavatko.views.SeznamReseniView` +- ``org/reseni/akt`` :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``resitel/reseni/`` (odevzdavatko_resitel_reseni) :class:`~odevzdavatko.views.ResitelReseniView` +""" from django.urls import path from seminar.utils import org_required, resitel_required, viewMethodSwitch, \ diff --git a/personalni/apps.py b/personalni/apps.py index 359f220c..47ba22cc 100644 --- a/personalni/apps.py +++ b/personalni/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/personalni/urls.py b/personalni/urls.py index 73a6f720..cbcdb035 100644 --- a/personalni/urls.py +++ b/personalni/urls.py @@ -1,3 +1,17 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``org/add_solution`` (seminar_vloz_reseni) :class:`~odevzdavatko.views.PosliReseniView` +- ``resitel/nahraj_reseni`` (seminar_nahraj_reseni) :class:`~odevzdavatko.views.NahrajReseniView` +- ``resitel/odevzdana_reseni/`` (seminar_resitel_odevzdana_reseni) :class:`~odevzdavatko.views.PrehledOdevzdanychReseni` +- ``org/reseni/`` (odevzdavatko_tabulka) :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``org/reseni/rocnik//`` (odevzdavatko_tabulka) :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``org/reseni///`` (odevzdavatko_reseni_resitele_k_problemu) :class:`~odevzdavatko.views.ReseniProblemuView` +- ``org/reseni//`` (odevzdavatko_detail_reseni) :func:`~seminar.utils.viewMethodSwitch` + :class:`~odevzdavatko.views.DetailReseniView` + :func:`~odevzdavatko.views.hodnoceniReseniView` +- ``org/reseni/all`` :class:`~odevzdavatko.views.SeznamReseniView` +- ``org/reseni/akt`` :class:`~odevzdavatko.views.TabulkaOdevzdanychReseniView` +- ``resitel/reseni/`` (odevzdavatko_resitel_reseni) :class:`~odevzdavatko.views.ResitelReseniView` +""" from django.urls import path from django.contrib.auth.decorators import login_required from . import views diff --git a/prednasky/urls.py b/prednasky/urls.py index b55de7c3..0a96aa59 100644 --- a/prednasky/urls.py +++ b/prednasky/urls.py @@ -1,3 +1,12 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``prednasky/`` :func:`~prednasky.views.newPrednaska` +- ``prednasky/hotovo`` :func:`~prednasky.views.Prednaska_hotovo` +- ``prednasky/metaseznam_prednasek`` (metaseznam-list) :class:`~prednasky.views.MetaSeznamListView` +- ``prednasky/seznam_prednasek//export`` (seznam-export) :func:`~prednasky.views.SeznamExportView` +- ``prednasky/seznam_prednasek//`` (seznam-list) :class:`~prednasky.views.SeznamListView` +""" from django.urls import path from seminar.utils import org_required, resitel_required from . import views diff --git a/seminar/__init__.py b/seminar/__init__.py index e69de29b..09ee5004 100644 --- a/seminar/__init__.py +++ b/seminar/__init__.py @@ -0,0 +1,6 @@ +""" +Zde bývalo vše. Teď tu zbývají všechny modely a části webu jako archiv, +přehled orgů, aktuální (k aktuálnímu číslu) věci, titulka a jak řešit. + +Také je tu generování testovacích (lokálních) dat. +""" \ No newline at end of file diff --git a/seminar/urls.py b/seminar/urls.py index 0e05f991..58fb0335 100644 --- a/seminar/urls.py +++ b/seminar/urls.py @@ -1,3 +1,35 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- Organizátoři + - ``o-nas/organizatori/`` (organizatori) :class:`~seminar.views.views_all.CojemamOrganizatoriView` + - ``o-nas/organizatori/organizovali/`` (stari_organizatori) :class:`~seminar.views.views_all.CojemamOrganizatoriStariView` +- Archiv + - ``archiv/rocniky/`` (seminar_archiv_rocniky) :class:`~seminar.views.views_all.ArchivView` + - ``archiv/temata/`` (seminar_archiv_temata) :class:`~seminar.views.views_all.ArchivTemataView` + - ``rocnik//`` (seminar_rocnik) :class:`~seminar.views.views_all.RocnikView` + - ``cislo/./`` (seminar_cislo) :class:`~seminar.views.views_all.CisloView` + - ``problem//`` (seminar_problem) :func:`~seminar.views.views_all.problemView` +- Zadání + - ``aktualni/zadani/`` (seminar_aktualni_zadani) :func:`~seminar.views.views_all.AktualniZadaniView` + - ``aktualni/vysledkova-listina/`` (seminar_aktualni_vysledky) :func:`~seminar.views.views_all.ZadaniAktualniVysledkovkaView` + - ``aktualni/rocnik/`` (seminar_aktualni_rocnik) :class:`~seminar.views.views_all.AktualniRocnikRedirectView` +- Články + - ``archiv/clanky/`` (clanky_resitel) :class:`~seminar.views.views_all.ClankyResitelView` +- Orgovské stránky + - ``rocnik//vysledkovka.tex`` (seminar_rocnik_vysledkovka) :class:`~seminar.views.views_all.RocnikVysledkovkaView` + - ``rocnik//resitele.csv`` (seminar_rocnik_resitele_csv) :func:`~seminar.views.views_all.resiteleRocnikuCsvExportView` + - ``cislo/./vysledkovka.tex`` (seminar_cislo_vysledkovka) :class:`~seminar.views.views_all.CisloVysledkovkaView` + - ``cislo/./obalky.pdf`` (seminar_cislo_obalky) :func:`~seminar.views.views_all.cisloObalkyView` + - ``cislo/./tituly.tex`` (seminar_cislo_titul) :func:`~seminar.views.views_all.TitulyView` + - ``stav`` (stav_databaze) :func:`~seminar.views.views_all.StavDatabazeView` + - ``cislo/./obalkovani`` (seminar_cislo_resitel_obalkovani) :class:`~seminar.views.views_all.ObalkovaniView` + - ``cislo/./odmeny/./`` (seminar_archiv_odmeny) :class:`~seminar.views.views_all.OdmenyView` +- Další + - `` `` (titulni_strana) :class:`~seminar.views.views_all.TitulniStranaView` + - ``jak-resit/`` (jak_resit) :class:`~seminar.views.views_all.JakResitView` + - ``stare-novinky/`` (stare_novinky) :class:`~seminar.views.views_all.StareNovinkyView` +""" from django.urls import path, include, re_path from . import views from .utils import org_required @@ -24,7 +56,6 @@ urlpatterns = [ #path('aktualni/temata/', views.ZadaniTemataView, name='seminar_temata'), path('aktualni/vysledkova-listina/', views.ZadaniAktualniVysledkovkaView, name='seminar_aktualni_vysledky'), path('aktualni/rocnik/', views.AktualniRocnikRedirectView.as_view(), name='seminar_aktualni_rocnik'), - path('stare-novinky/', views.StareNovinkyView.as_view(), name='stare_novinky'), # Clanky path('archiv/clanky/', views.ClankyResitelView.as_view(), name='clanky_resitel'), @@ -73,4 +104,5 @@ urlpatterns = [ path('', views.TitulniStranaView.as_view(), name='titulni_strana'), path('jak-resit/', views.JakResitView.as_view(), name='jak_resit'), + path('stare-novinky/', views.StareNovinkyView.as_view(), name='stare_novinky'), ] diff --git a/soustredeni/apps.py b/soustredeni/apps.py index 5d282341..a0a8dae5 100644 --- a/soustredeni/apps.py +++ b/soustredeni/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/treenode/apps.py b/treenode/apps.py index 95139dc6..8e7df6fc 100644 --- a/treenode/apps.py +++ b/treenode/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/treenode/urls.py b/treenode/urls.py index 60dc88ad..1b6444bb 100644 --- a/treenode/urls.py +++ b/treenode/urls.py @@ -1,3 +1,8 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- Zatím tu nic moc není… +""" from django.urls import path, re_path from . import views diff --git a/various/apps.py b/various/apps.py index c24a4428..bf6023f0 100644 --- a/various/apps.py +++ b/various/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig diff --git a/various/autentizace/urls.py b/various/autentizace/urls.py index 83c8e50e..a89ff89e 100644 --- a/various/autentizace/urls.py +++ b/various/autentizace/urls.py @@ -1,3 +1,16 @@ +""" +Soubor sloužící jako „router“, tj. zde se definují url adresy a na co ukazují: + +- ``prihlasit/`` (login) :class:`~various.autentizace.views.LoginView` +- ``login/`` :class:`django.views.generic.base.RedirectView` předchozího +- ``odhlasit/`` (logout) :class:`~various.autentizace.views.LogoutView` +- ``logout/`` :class:`django.views.generic.base.RedirectView` předchozího +- ``reset-hesla/`` (reset_password) :class:`~various.autentizace.views.PasswordResetView` +- ``zmena-hesla/`` (change_password) :class:`~various.autentizace.views.PasswordChangeView` +- ``zmena-hesla/2/`` (reset_password_done) :class:`~various.autentizace.views.PasswordResetDoneView` +- ``reset-hesla/potvrzeni///`` (reset_password_confirm) :class:`~various.autentizace.views.PasswordResetConfirmView` +- ``reset-hesla/hotovo/`` (reset_password_complete) :class:`~various.autentizace.views.PasswordResetCompleteView` +""" from django.urls import path from . import views from django.views.generic.base import RedirectView diff --git a/vysledkovky/apps.py b/vysledkovky/apps.py index 7221864c..de1c2bde 100644 --- a/vysledkovky/apps.py +++ b/vysledkovky/apps.py @@ -1,3 +1,6 @@ +""" +Soubor sloužící k pojmenování a jiným nastavením djangovské aplikace. +""" from django.apps import AppConfig From 7f1d4062422a60e691c61b5174faaf6728dfaabc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Mon, 7 Mar 2022 21:56:09 +0100 Subject: [PATCH 8/9] =?UTF-8?q?P=C5=99esunut=C3=AD=20apidoc=20z=20conf.py?= =?UTF-8?q?=20do=20Makefilu.=20Fuj=20Windows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Makefile | 2 +- docs/conf.py | 4 ---- docs/make.bat | 35 ----------------------------------- docs/sphinx.rst | 4 ---- 4 files changed, 1 insertion(+), 44 deletions(-) delete mode 100644 docs/make.bat diff --git a/docs/Makefile b/docs/Makefile index 61eab5c7..b12affc9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,5 +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 + sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index 584272c8..24f2bfed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -79,7 +79,3 @@ autodoc_member_order = "bysource" # Nezobrazování zděděné (ze super tříd) dokumentace TODO nefunguje? autodoc_inherit_docstrings = False - -# Spouštění sphinx-apidoc -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/make.bat b/docs/make.bat deleted file mode 100644 index 8084272b..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/sphinx.rst b/docs/sphinx.rst index 99a92d74..fea2c1a7 100644 --- a/docs/sphinx.rst +++ b/docs/sphinx.rst @@ -11,10 +11,6 @@ Sphinx se píše v rst: `Návod na syntaxi rst`_ `Cheat sheet`_ .. _Návod na syntaxi rst: https://sphinx-tutorial.readthedocs.io/step-1/#sections .. _Cheat sheet: https://sphinx-tutorial.readthedocs.io/cheatsheet/ -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í:: From 87e2833a892f1e763f7602b0fea1ee406fef1085 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=C3=A1=C5=A1=20Havelka?= Date: Mon, 7 Mar 2022 22:41:59 +0100 Subject: [PATCH 9/9] Markdown ve sphinxu. --- docs/conf.py | 8 +++++++- docs/index.rst | 1 + docs/zapisy/zapisy.rst | 5 +++++ 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 docs/zapisy/zapisy.rst diff --git a/docs/conf.py b/docs/conf.py index 24f2bfed..d597faf2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,7 +34,8 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', - 'sphinx.ext.autosectionlabel' + 'sphinx.ext.autosectionlabel', + 'myst_parser', ] # Add any paths that contain templates here, relative to this directory. @@ -79,3 +80,8 @@ autodoc_member_order = "bysource" # Nezobrazování zděděné (ze super tříd) dokumentace TODO nefunguje? autodoc_inherit_docstrings = False + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} diff --git a/docs/index.rst b/docs/index.rst index 0f779e42..10d6016f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Vítejte v dokumentaci M&Mího webu! sphinx dalsi_soubory modules/modules + zapisy/zapisy diff --git a/docs/zapisy/zapisy.rst b/docs/zapisy/zapisy.rst new file mode 100644 index 00000000..1150a65c --- /dev/null +++ b/docs/zapisy/zapisy.rst @@ -0,0 +1,5 @@ +Zápisy +====== + +.. toctree:: + 2021-12-06-testovani_dokumentace_codereview \ No newline at end of file