Development: Update docs requirements and align the settings with the…

… latest version

.github/workflows/build.yml

@@ -7,7 +7,7 @@ on:
     branches: [ develop ]
 
 env:
-  node: 16.x
+  node: 22
 
 jobs:
   build:
@@ -16,10 +16,10 @@ jobs:
 
     steps:
       - name: Setup Node.js '${{ env.node }}'
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: '${{ env.node }}'
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Cache node modules
         uses: actions/cache@v2
         with:

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 TUM Applied Software Engineering
+Copyright (c) 2025 TUM Applied Education Technologies
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/.gitignore

@@ -0,0 +1,6 @@
+_build/
+.venv/
+.idea/
+__pycache__/
+.env
+venv

docs/.readthedocs.yaml

@@ -0,0 +1,13 @@
+---
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+sphinx:
+  fail_on_warning: true
+  configuration: docs/conf.py
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/Dockerfile

@@ -0,0 +1,15 @@
+FROM sphinxdoc/sphinx
+
+WORKDIR /docs
+# create non-root user to be able to edit the generated files without root access later
+RUN groupadd -g 1000 sphinx-user \
+    && useradd -ms /bin/bash -u 1000 -g 1000 sphinx-user \
+    && chown 1000:1000 /docs
+ADD requirements.txt /docs
+RUN pip3 install -r requirements.txt
+
+USER sphinx-user
+EXPOSE 8000
+# use the autobuild as default command
+ENV SPHINXOPTS="--port 8000 --host 0.0.0.0"
+CMD exec make livehtml

docs/Makefile

@@ -3,15 +3,19 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+# -W: treat warnings as errors
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/_static/css/style.css

@@ -0,0 +1,6 @@
+/* This import resolves when built */
+@import url("theme.css");
+
+.wy-body-for-nav .wy-nav-content {
+    max-width: none;
+}

docs/conf.py

@@ -0,0 +1,81 @@
+# 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
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Apollon'
+copyright = '2025, Applied Education Technologies, Technical University of Munich'
+author = 'Applied Education Technologies, Technical University of Munich'
+
+
+# -- General configuration ---------------------------------------------------
+
+# The document name of the “main” document, that is, the document
+# that contains the root toctree directive.
+master_doc = "index"
+
+# 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_rtd_theme",
+]
+
+# 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', 'venv']
+
+linkcheck_ignore = [
+    r'http(s)?://.*localhost(:\d+)?/?',
+    r'https://Apollon.cs.hm.edu/',  # DNS entry no longer exists
+    r'https://bamboo.ase.in.tum.de/build/admin/edit/.*',
+    r'https://hermes.Apollon.cit.tum.de/',  # expired certificate
+    # IEEE server returns code 418 when checking links
+    r'https://doi.org/10.1109/CSEET58097.2023.00020',
+    r'https://doi.org/10.1109/CSEET58097.2023.00021',
+    r'https://doi.org/10.1109/CSEET58097.2023.00031',
+    r'https://doi.org/10.1109/CSEET58097.2023.00037',
+    r'https://doi.org/10.1109/ITHET50392.2021.9759809',
+]
+# do not check anchors on websites that need JavaScript to load the content
+# the anchor points to
+linkcheck_anchors_ignore_for_url = [
+    r"https://angular.io/guide/.*",
+    r"https://github.com/.*",
+    r"https://k3d.io/.*"
+]
+
+# -- 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 = 'sphinx_rtd_theme'
+html_context = {
+    "display_github": True,
+    "github_user": "ls1intum",
+    "github_repo": "Apollon",
+    "github_version": "develop",
+    "conf_py_path": "/docs/",
+}
+html_style = 'css/style.css'
+
+# 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']

docs/source/dev/examples.rst → docs/dev/examples.rst

@@ -1,6 +1,6 @@
-##########
+########
 Examples
-##########
+########
 
 
 Example of Feature Definition of Element
@@ -38,54 +38,56 @@ The representation is the defined in the corresponding component class, in our e
 
 .. code-block:: typescript
 
-   export const UMLClassifierComponent: FunctionComponent<Props> = ({ element, children }) => (
-      <g>
-        <rect width="100%" height={element.stereotype ? 50 : 40} />
-        <rect
-          y={element.stereotype ? 50 : 40}
-          width="100%"
-          height={element.bounds.height - (element.stereotype ? 50 : 40)}
-          fill="white"
-        />
-        {element.stereotype ? (
-          <svg height={50}>
-            <text x="50%" y="50%" dominantBaseline="middle" textAnchor="middle" fontWeight="bold" pointerEvents="none">
-              <tspan x="50%" dy={-8} textAnchor="middle" fontSize="85%">
-                {`«${element.stereotype}»`}
-              </tspan>
-              <tspan
+    export const UMLClassifierComponent: FunctionComponent<Props> = ({ element, children }) => {
+      const fontStyle = element.italic ? 'italic' : undefined;
+      const textDecoration = element.underline ? 'underline' : undefined;
+      const headerPath = `M 0 ${element.headerHeight} H ${element.bounds.width}`;
+      const dividerPath = `M 0 ${element.deviderPosition} H ${element.bounds.width}`;
+
+      return (
+        <g>
+          <rect width="100%" height={element.stereotype ? 50 : 40} />
+          <rect
+            y={element.stereotype ? 50 : 40}
+            width="100%"
+            height={element.bounds.height - (element.stereotype ? 50 : 40)}
+            fill="white"
+          />
+          {element.stereotype ? (
+            <svg height={50}>
+              <text x="50%" y="50%" dominantBaseline="middle" textAnchor="middle" fontWeight="bold" pointerEvents="none">
+                {/* «${element.stereotype}» */}
+                <tspan x="50%" dy={-8} textAnchor="middle" fontSize="85%">
+                  {/* «${element.stereotype}» */}
+                </tspan>
+                <tspan x="50%" dy={18} textAnchor="middle" fontStyle={fontStyle} textDecoration={textDecoration}>
+                  {element.name}
+                </tspan>
+              </text>
+            </svg>
+          ) : (
+            <svg height={40}>
+              <text
                 x="50%"
-                dy={18}
+                y="50%"
+                dominantBaseline="middle"
                 textAnchor="middle"
-                fontStyle={element.italic ? 'italic' : undefined}
-                textDecoration={element.underline ? 'underline' : undefined}
+                fontWeight="bold"
+                fontStyle={fontStyle}
+                textDecoration={textDecoration}
+                pointerEvents="none"
               >
                 {element.name}
-              </tspan>
-            </text>
-          </svg>
-        ) : (
-          <svg height={40}>
-            <text
-              x="50%"
-              y="50%"
-              dominantBaseline="middle"
-              textAnchor="middle"
-              fontWeight="bold"
-              fontStyle={element.italic ? 'italic' : undefined}
-              textDecoration={element.underline ? 'underline' : undefined}
-              pointerEvents="none"
-            >
-              {element.name}
-            </text>
-          </svg>
-        )}
-        {children}
-        <rect width="100%" height="100%" stroke="black" fill="none" pointerEvents="none" />
-        <path d={`M 0 ${element.headerHeight} H ${element.bounds.width}`} stroke="black" />
-        <path d={`M 0 ${element.deviderPosition} H ${element.bounds.width}`} stroke="black" />
-      </g>
-   );
+              </text>
+            </svg>
+          )}
+          {children}
+          <rect width="100%" height="100%" stroke="black" fill="none" pointerEvents="none" />
+          <path d={headerPath} stroke="black" />
+          <path d={dividerPath} stroke="black" />
+        </g>
+      );
+    };
 
 It implements the visual representation, which always made up of svg elements.
 

docs/source/dev/general-concepts.rst → docs/dev/general-concepts.rst

@@ -1,6 +1,6 @@
-#################
+################
 General Concepts
-#################
+################
 
 The ApollonEditor is a UML modeling editor which can be used to visualize and
 modify UML Diagrams. It can load and

docs/source/dev/realtime-collaboration.rst → docs/dev/realtime-collaboration.rst

@@ -1,8 +1,8 @@
-####################
+######################
 Realtime Collaboration
-####################
+######################
 
-Apollon supports realtime collaboration by tracking and emitting patches when changes happen to the diagram. The patches are in the format of `RFC 6902`_ standard (i.e. `JSON Patch`_), so that they can be applied to Apollon diagrams by cliients in different languages and in various stacks (i.e. other clients, on the server, etc.).
+Apollon supports realtime collaboration by tracking and emitting patches when changes happen to the diagram. The patches are in the format of `RFC 6902`_ standard (i.e. `JSON Patch`_), so that they can be applied to Apollon diagrams by clients in different languages and in various stacks (i.e. other clients, on the server, etc.).
 
 Tracking changes happens through the `patcher service <Patcher Service Code_>`_. This service is written in a general form and then configured for the specific case of Apollon diagrams: the core of the service is the `Patcher <Patcher Code_>`_ class, which tracks changes to a given object and notifies subscribers to those changes, and allows applying patches, which might have been generated by other clients and received via the network, to said object. The `Patcher` is connected to Apollon's application state using the a `Redux Middleware`_ called `PatcherMiddleware <Patcher Middleware Code_>`_, which filters all incoming actions according to a given
 configuration and asks the `Patcher` to check for changes when necessary, and a `Redux Reducer`_ called `PatcherReducer <Patcher Reducer Code_>`_, which is responsible for applying patches to the application state using the `Patcher <Patcher Code_>`_.
@@ -14,9 +14,9 @@ configuration and asks the `Patcher` to check for changes when necessary, and a
    Flow of Realtime Collaboration in Apollon
 
 
-**********************
+*************************
 Diagram Schema Guidelines
-**********************
+*************************
 
 The realtime collaboration system imposes some constraints on the schema of Apollon diagrams in order to be able to properly reconcile potentially conflicting changes between clients while sticking to the standard `JSON Patch`_ format. The constraints should be considered specifically when adding new diagram types.
 
@@ -25,7 +25,7 @@ Follow these guidelines to ensure any diagram type works properly with realtime
 - Use maps instead of arrays as much as possible. If you have a list of items with unique IDs, use a map with the keys set as said IDs to the each item, instead of an array.
 - For representing sets of unique IDs, use maps mapping IDs to boolean values (i.e. inclusion maps), instead of arrays.
 
-Dont't do this:
+Don't do this:
 
 .. code-block:: typescript
 
@@ -58,7 +58,7 @@ In scenarios where you need to represent a list of items with an array, for exam
 Stuttering Prevention
 **********************
 
-The `Patcher <Patcher Code_>`_ also utilises a stuttering prevention mechanism to avoid applying patches that are optimistically predicted to be redundant. To this end, the `Patch Verifier <Patch Verifier Code_>`_ class is used to sign all patches created locally and record their corresponding path in the `JSON Patch`. The client assumes that the integrating platform will resend this patch to all clients, including the one that created it, and so will ignore other incoming patches on the same path until the self-signed patch is received, as such patches would be overriden by the self-signed patch anyway.
+The `Patcher <Patcher Code_>`_ also utilises a stuttering prevention mechanism to avoid applying patches that are optimistically predicted to be redundant. To this end, the `Patch Verifier <Patch Verifier Code_>`_ class is used to sign all patches created locally and record their corresponding path in the `JSON Patch`. The client assumes that the integrating platform will resend this patch to all clients, including the one that created it, and so will ignore other incoming patches on the same path until the self-signed patch is received, as such patches would be overridden by the self-signed patch anyway.
 
 .. _RFC 6902: https://tools.ietf.org/html/rfc6902
 .. _JSON Patch: http://jsonpatch.com/
@@ -69,4 +69,4 @@ The `Patcher <Patcher Code_>`_ also utilises a stuttering prevention mechanism t
 .. _Patcher Compare Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/compare.ts
 .. _Patcher Middleware Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patcher-middleware.ts
 .. _Patcher Reducer Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patcher-reducer.ts
-.. _Patch Verifier Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patch-verifier.ts
+.. _Patch Verifier Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patch-verifier.ts

docs/source/dev/repository-overview.rst → docs/dev/repository-overview.rst

@@ -20,8 +20,7 @@ On the top level we have the separation between `components`, `i18n`, `packages`
 
 #. `packages` contains the code which is specific to UML diagram types. A package describes one UML diagram type (location: src/main/packages/) and has:
 
-    * a component for each UML element type available in the specific UML diagram type, which describes the appearance of the elements. (Reference example)
-For example in `src/main/packages/uml-object-diagram` exists
+    * a component for each UML element type available in the specific UML diagram type, which describes the appearance of the elements. (Reference example) For example in `src/main/packages/uml-object-diagram` exists
 
         * uml-object-attribute
 

docs/source/index.rst → docs/index.rst

@@ -1,8 +1,3 @@
-.. Apollon documentation master file, created by
-   sphinx-quickstart on Mon Sep  7 17:48:38 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Apollon's documentation!
 ===================================