Utils/setup.sh

@@ -10,11 +10,19 @@ rm -rf venv/
 
 # Setup Python Environment
 # Requires: Virtualenv, appropriate Python installation
-virtualenv venv -p python3.9
+virtualenv venv -p python3.11
 source venv/bin/activate
 pip install --upgrade setuptools pip wheel
 pip install -r requirements.txt
 
+# set environment variable when we want to update in production
+if [ "$1" = "--prod" ]; then
+    export DJANGO_SETTINGS_MODULE=AKPlanning.settings_production
+fi
+if [ "$1" = "--ci" ]; then
+    export DJANGO_SETTINGS_MODULE=AKPlanning.settings_ci
+fi
+
 # Setup database
 python manage.py migrate
 
@@ -26,4 +34,12 @@ python manage.py compilemessages -l de_DE
 # Credentials are entered interactively on CLI
 python manage.py createsuperuser
 
+# Generate documentation (but not for CI use)
+if [ -n "$1" = "--ci" ]; then
+    cd docs
+    make html
+    cd ..
+fi
+
+
 deactivate

Utils/test.sh

+#!/usr/bin/env bash
+# Test the AKPlanning setup
+# execute as Utils/test.sh
+
+# activate virtualenv when necessary
+if [ -z ${VIRTUAL_ENV+x} ]; then
+    source venv/bin/activate
+fi
+
+# enable really all warnings, some of them are silenced by default
+for arg in "$@"; do
+    if [[ "$arg" == "--all" ]]; then
+        export PYTHONWARNINGS=all
+    fi
+done
+
+# in case of checking production setup
+for arg in "$@"; do
+    if [[ "$arg" == "--prod" ]]; then
+      export DJANGO_SETTINGS_MODULE=AKPlanning.settings_production
+      ./manage.py test --deploy
+    fi
+done
+
+# run tests
+./manage.py test

Utils/update.sh

@@ -27,4 +27,10 @@ pip install --upgrade -r requirements.txt
 ./manage.py collectstatic --noinput
 ./manage.py compilemessages -l de_DE
 
+
+# Update documentation
+cd docs
+make html
+cd ..
+
 touch AKPlanning/wsgi.py

docs/.gitignore

+_build/
+code/

docs/Makefile

+# 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)

docs/code.rst

+Code
+=====
+
+.. toctree::
+    code/AKDashboard
+    code/AKModel
+    code/AKOnline
+    code/AKPlan
+    code/AKScheduling
+    code/AKSubmission

docs/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
+from recommonmark.parser import CommonMarkParser
+import django
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'AK Planning'
+copyright = '2025, N. Geisler, B. Hättasch & more'
+author = 'N. Geisler, B. Hättasch & more'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinxcontrib.apidoc',   # runs sphinx-apidoc automatically as part of sphinx-build
+    'sphinx.ext.autodoc',     # the autodoc extensions uses files generated by apidoc
+    "sphinx.ext.autosummary",
+    "sphinxcontrib_django",
+    'sphinx.ext.viewcode',    # enable viewing autodoc'd code
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Django specific settings ------------------------------------------------
+
+# Add source directory to sys.path
+sys.path.insert(0, os.path.abspath(".."))
+
+# Configure the path to the Django settings module
+django_settings = "AKPlanning.settings"
+os.environ['DJANGO_SETTINGS_MODULE'] = django_settings
+
+django.setup()
+
+# Include the database table names of Django models
+django_show_db_tables = True                # Boolean, default: False
+# Add abstract database tables names (only takes effect if django_show_db_tables is True)
+django_show_db_tables_abstract = True       # Boolean, default: False
+
+# Auto-generate API documentation.
+os.environ['SPHINX_APIDOC_OPTIONS'] = "members,show-inheritance"
+
+# -- Input ----
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
+# -- Extension Conf ----
+
+autodoc_member_order = 'bysource'
+autodoc_inherit_docstrings = False
+
+apidoc_module_dir = '../'
+apidoc_output_dir = 'code'
+apidoc_excluded_paths = ['*/migrations',
+                         'AKPlanning/',
+                         'manage.py',
+                         'docs',
+                         'locale',
+                         'Utils',
+                         '*/urls.py',
+                         ]
+apidoc_separate_modules = True
+apidoc_toc_file = False
+apidoc_module_first = True
+apidoc_extra_args = ['-f']
+apidoc_project = project
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_static_path = ['_static']
+html_theme = 'sphinx_rtd_theme'

docs/index.rst

+.. AK Planning documentation master file, created by
+   sphinx-quickstart on Wed Jun 21 09:54:11 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Start
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage/usage
+   code
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%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
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/usage/usage.rst

+Usage
+=====
+
+.. toctree::
+

locale/de_DE/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-08-15 18:26+0000\n"
+"POT-Creation-Date: 2023-08-16 16:30+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -18,39 +18,39 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
 
-#: AKOnline/models.py:10
-msgid "URL"
-msgstr "URL"
-
-#: AKOnline/models.py:10
-msgid "URL to the room or server"
-msgstr "URL zum Raum/Server"
-
-#: AKOnline/models.py:13
-msgid "Virtual Room"
-msgstr "Virtueller Raum"
-
-#: AKOnline/models.py:14
-msgid "Virtual Rooms"
-msgstr "Virtuelle Räume"
-
-#: templates/base.html:29
+#: templates/base.html:43
 msgid ""
 "Are you sure you want to change the language now? This will clear the form!"
 msgstr "Wirklich jetzt die Sprache ändern? Das wird das Formular zurücksetzen!"
 
-#: templates/base.html:94
+#: templates/base.html:108
 msgid "Go to backend"
 msgstr "Zum Backend"
 
-#: templates/base.html:100
+#: templates/base.html:109
+msgid "Docs"
+msgstr "Doku"
+
+#: templates/base.html:115
 msgid "Impress"
 msgstr "Impressum"
 
-#: templates/base.html:103
+#: templates/base.html:118
 msgid "This software is open source"
 msgstr "Diese Software ist Open Source"
 
+#~ msgid "URL to the room or server"
+#~ msgstr "URL zum Raum/Server"
+
+#~ msgid "Room"
+#~ msgstr "Raum"
+
+#~ msgid "Virtual Room"
+#~ msgstr "Virtueller Raum"
+
+#~ msgid "Virtual Rooms"
+#~ msgstr "Virtuelle Räume"
+
 #~ msgid "Scheduling for"
 #~ msgstr "Scheduling für"
 
@@ -66,9 +66,6 @@ msgstr "Diese Software ist Open Source"
 #~ msgid "Event (Vertical)"
 #~ msgstr "Event (vertikal)"
 
-#~ msgid "Room"
-#~ msgstr "Raum"
-
 #~ msgid "Event Status"
 #~ msgstr "Event-Status"
 

pylintrc

+[MAIN]
+
+ignore=urls.py, migrations, AKPlanning
+
+load-plugins=
+    pylint_django,
+    pylint_django.checkers.migrations
+
+django-settings-module=AKPlanning.settings
+
+disable=
+    C0114, # missing-module-docstring
+
+
+[FORMAT]
+
+# Maximum number of characters on a single line.
+max-line-length=120
+
+indent-string='    '
+
+
+
+[SIMILARITIES]
+
+# Minimum lines number of a similarity.
+min-similarity-lines=6
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=yes
+
+# Signatures are removed from the similarity computation
+ignore-signatures=yes
+
+
+[BASIC]
+
+# Regular expression matching correct module names
+module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+)|((tags_)*AK[A-Z][a-z0-9_]+))$
+
+# Good variable names which should always be accepted, separated by a comma
+good-names=i,j,k,a,e,ak,tz,_,pk
+
+# Allow single-letter variables and enforce lowercase variables with underscores otherwise
+variable-rgx=[a-z_][a-z0-9_]{0,30}$
+
+
+[TYPECHECK]
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# List of classes names for which member attributes should not be checked
+# (useful for classes with attributes dynamically set).
+ignored-classes=SQLObject,WSGIRequest
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E0201 when accessed.
+generated-members=objects,DoesNotExist,id,pk,_meta,base_fields,context
+
+# List of method names used to declare (i.e. assign) instance attributes
+defining-attr-methods=__init__,__new__,setUp
+
+
+[DESIGN]
+
+max-parents=15
+
+max-args=8

renovate.json

+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json"
+}

requirements.txt

-Django==4.1.5
-django-bootstrap5==22.2
-fontawesomefree==6.2.1 # Makes static files (css, fonts) available locally
-django-fontawesome-6==1.0.0.0 # Provides an icon field for models and forms as well as handy shortcuts to render icons
-django-split-settings==1.2.0
-django-timezone-field==5.0
-djangorestframework==3.14.0
-django-simple-history==3.2.0
-django-registration-redux==2.11
-django-debug-toolbar==3.8.1
-django-bootstrap-datepicker-plus==5.0.2
+Django==5.1.6
+django-betterforms==2.0.0
+django-bootstrap-datepicker-plus==5.0.5
+django-bootstrap5==25.1
+django-compressor==4.5.1
+django-debug-toolbar==5.0.1
+django-fontawesome-6==1.0.0.0  # Provides an icon field for models and forms as well as handy shortcuts to render icons
+django-libsass==0.9
+django-registration-redux==2.13
+django-simple-history==3.8.0
+django-split-settings==1.3.2
 django-tex==1.1.10
-django-csp==3.7
-mysqlclient==2.1.1  # for production deployment
-tzdata==2022.7
+django-timezone-field==7.1
+django_csp==3.8
+djangorestframework==3.15.2
+
+fontawesomefree==6.6.0  # Makes static files (css, fonts) available locally
+mysqlclient==2.2.7  # for production deployment
+tzdata==2025.1
+
+# Documentation
+Sphinx==8.2.3
+sphinx-rtd-theme==3.0.2
+sphinxcontrib-apidoc==0.5.0
+sphinxcontrib-django==2.5.0
+recommonmark==0.7.1
+django-docs==0.3.3

setup.cfg

+[pycodestyle]
+max-line-length = 120
+exclude = migrations,static
+max-complexity = 11

static_common/common/css/admin-bootstrap.css

-/*
-    Load both the django admin base style and bootstrap -- but make sure bootstrap is loaded first to override all critical theme settings from bootstrap with the default admin style.
-    This especially fixes the dark theme.
-*/
-@import "/static/common/css/bootstrap.css";
-@import "../../admin/css/base.css";
-@import "/static/common/css/custom.css";

static_common/common/js/availabilities.js

@@ -53,6 +53,10 @@ function createAvailabilityEditors(timezone, language, startDate, endDate, slotR
         let plan = new FullCalendar.Calendar(editor[0], {
             timeZone: timezone,
             themeSystem: 'bootstrap5',
+            buttonIcons: {
+                prev: 'ignore fa-solid fa-angle-left',
+                next: 'ignore fa-solid fa-angle-right',
+            },
             locale: language,
             schedulerLicenseKey: 'GPL-My-Project-Is-Open-Source',
             editable: editable,
@@ -68,6 +72,7 @@ function createAvailabilityEditors(timezone, language, startDate, endDate, slotR
                     },
                 }
             },
+            contentHeight: 'auto',
             allDaySlot: true,
             events: data.availabilities,
             eventBackgroundColor: eventColor,

static_common/common/vendor/bootstrap/scss/_accordion.scss

+//
+// Base styles
+//
+
+.accordion {
+  // scss-docs-start accordion-css-vars
+  --#{$prefix}accordion-color: #{$accordion-color};
+  --#{$prefix}accordion-bg: #{$accordion-bg};
+  --#{$prefix}accordion-transition: #{$accordion-transition};
+  --#{$prefix}accordion-border-color: #{$accordion-border-color};
+  --#{$prefix}accordion-border-width: #{$accordion-border-width};
+  --#{$prefix}accordion-border-radius: #{$accordion-border-radius};
+  --#{$prefix}accordion-inner-border-radius: #{$accordion-inner-border-radius};
+  --#{$prefix}accordion-btn-padding-x: #{$accordion-button-padding-x};
+  --#{$prefix}accordion-btn-padding-y: #{$accordion-button-padding-y};
+  --#{$prefix}accordion-btn-color: #{$accordion-button-color};
+  --#{$prefix}accordion-btn-bg: #{$accordion-button-bg};
+  --#{$prefix}accordion-btn-icon: #{escape-svg($accordion-button-icon)};
+  --#{$prefix}accordion-btn-icon-width: #{$accordion-icon-width};
+  --#{$prefix}accordion-btn-icon-transform: #{$accordion-icon-transform};
+  --#{$prefix}accordion-btn-icon-transition: #{$accordion-icon-transition};
+  --#{$prefix}accordion-btn-active-icon: #{escape-svg($accordion-button-active-icon)};
+  --#{$prefix}accordion-btn-focus-border-color: #{$accordion-button-focus-border-color};
+  --#{$prefix}accordion-btn-focus-box-shadow: #{$accordion-button-focus-box-shadow};
+  --#{$prefix}accordion-body-padding-x: #{$accordion-body-padding-x};
+  --#{$prefix}accordion-body-padding-y: #{$accordion-body-padding-y};
+  --#{$prefix}accordion-active-color: #{$accordion-button-active-color};
+  --#{$prefix}accordion-active-bg: #{$accordion-button-active-bg};
+  // scss-docs-end accordion-css-vars
+}
+
+.accordion-button {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  padding: var(--#{$prefix}accordion-btn-padding-y) var(--#{$prefix}accordion-btn-padding-x);
+  @include font-size($font-size-base);
+  color: var(--#{$prefix}accordion-btn-color);
+  text-align: left; // Reset button style
+  background-color: var(--#{$prefix}accordion-btn-bg);
+  border: 0;
+  @include border-radius(0);
+  overflow-anchor: none;
+  @include transition(var(--#{$prefix}accordion-transition));
+
+  &:not(.collapsed) {
+    color: var(--#{$prefix}accordion-active-color);
+    background-color: var(--#{$prefix}accordion-active-bg);
+    box-shadow: inset 0 calc(-1 * var(--#{$prefix}accordion-border-width)) 0 var(--#{$prefix}accordion-border-color); // stylelint-disable-line function-disallowed-list
+
+    &::after {
+      background-image: var(--#{$prefix}accordion-btn-active-icon);
+      transform: var(--#{$prefix}accordion-btn-icon-transform);
+    }
+  }
+
+  // Accordion icon
+  &::after {
+    flex-shrink: 0;
+    width: var(--#{$prefix}accordion-btn-icon-width);
+    height: var(--#{$prefix}accordion-btn-icon-width);
+    margin-left: auto;
+    content: "";
+    background-image: var(--#{$prefix}accordion-btn-icon);
+    background-repeat: no-repeat;
+    background-size: var(--#{$prefix}accordion-btn-icon-width);
+    @include transition(var(--#{$prefix}accordion-btn-icon-transition));
+  }
+
+  &:hover {
+    z-index: 2;
+  }
+
+  &:focus {
+    z-index: 3;
+    border-color: var(--#{$prefix}accordion-btn-focus-border-color);
+    outline: 0;
+    box-shadow: var(--#{$prefix}accordion-btn-focus-box-shadow);
+  }
+}
+
+.accordion-header {
+  margin-bottom: 0;
+}
+
+.accordion-item {
+  color: var(--#{$prefix}accordion-color);
+  background-color: var(--#{$prefix}accordion-bg);
+  border: var(--#{$prefix}accordion-border-width) solid var(--#{$prefix}accordion-border-color);
+
+  &:first-of-type {
+    @include border-top-radius(var(--#{$prefix}accordion-border-radius));
+
+    .accordion-button {
+      @include border-top-radius(var(--#{$prefix}accordion-inner-border-radius));
+    }
+  }
+
+  &:not(:first-of-type) {
+    border-top: 0;
+  }
+
+  // Only set a border-radius on the last item if the accordion is collapsed
+  &:last-of-type {
+    @include border-bottom-radius(var(--#{$prefix}accordion-border-radius));
+
+    .accordion-button {
+      &.collapsed {
+        @include border-bottom-radius(var(--#{$prefix}accordion-inner-border-radius));
+      }
+    }
+
+    .accordion-collapse {
+      @include border-bottom-radius(var(--#{$prefix}accordion-border-radius));
+    }
+  }
+}
+
+.accordion-body {
+  padding: var(--#{$prefix}accordion-body-padding-y) var(--#{$prefix}accordion-body-padding-x);
+}
+
+
+// Flush accordion items
+//
+// Remove borders and border-radius to keep accordion items edge-to-edge.
+
+.accordion-flush {
+  .accordion-collapse {
+    border-width: 0;
+  }
+
+  .accordion-item {
+    border-right: 0;
+    border-left: 0;
+    @include border-radius(0);
+
+    &:first-child { border-top: 0; }
+    &:last-child { border-bottom: 0; }
+
+    .accordion-button {
+      &,
+      &.collapsed {
+        @include border-radius(0);
+      }
+    }
+  }
+}

static_common/common/vendor/bootstrap/scss/_alert.scss

+//
+// Base styles
+//
+
+.alert {
+  // scss-docs-start alert-css-vars
+  --#{$prefix}alert-bg: transparent;
+  --#{$prefix}alert-padding-x: #{$alert-padding-x};
+  --#{$prefix}alert-padding-y: #{$alert-padding-y};
+  --#{$prefix}alert-margin-bottom: #{$alert-margin-bottom};
+  --#{$prefix}alert-color: inherit;
+  --#{$prefix}alert-border-color: transparent;
+  --#{$prefix}alert-border: #{$alert-border-width} solid var(--#{$prefix}alert-border-color);
+  --#{$prefix}alert-border-radius: #{$alert-border-radius};
+  // scss-docs-end alert-css-vars
+
+  position: relative;
+  padding: var(--#{$prefix}alert-padding-y) var(--#{$prefix}alert-padding-x);
+  margin-bottom: var(--#{$prefix}alert-margin-bottom);
+  color: var(--#{$prefix}alert-color);
+  background-color: var(--#{$prefix}alert-bg);
+  border: var(--#{$prefix}alert-border);
+  @include border-radius(var(--#{$prefix}alert-border-radius));
+}
+
+// Headings for larger alerts
+.alert-heading {
+  // Specified to prevent conflicts of changing $headings-color
+  color: inherit;
+}
+
+// Provide class for links that match alerts
+.alert-link {
+  font-weight: $alert-link-font-weight;
+}
+
+
+// Dismissible alerts
+//
+// Expand the right padding and account for the close button's positioning.
+
+.alert-dismissible {
+  padding-right: $alert-dismissible-padding-r;
+
+  // Adjust close link position
+  .btn-close {
+    position: absolute;
+    top: 0;
+    right: 0;
+    z-index: $stretched-link-z-index + 1;
+    padding: $alert-padding-y * 1.25 $alert-padding-x;
+  }
+}
+
+
+// scss-docs-start alert-modifiers
+// Generate contextual modifier classes for colorizing the alert.
+
+@each $state, $value in $theme-colors {
+  $alert-background: shift-color($value, $alert-bg-scale);
+  $alert-border: shift-color($value, $alert-border-scale);
+  $alert-color: shift-color($value, $alert-color-scale);
+
+  @if (contrast-ratio($alert-background, $alert-color) < $min-contrast-ratio) {
+    $alert-color: mix($value, color-contrast($alert-background), abs($alert-color-scale));
+  }
+  .alert-#{$state} {
+    @include alert-variant($alert-background, $alert-border, $alert-color);
+  }
+}
+// scss-docs-end alert-modifiers