Add Sphinx Documentation

.github/workflows/docs.yaml

@@ -0,0 +1,26 @@
+name: Publish Sphinx Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish_sphinx_docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - name: Install dependencies
+        run: uv sync
+      - name: Sphinx build
+        run: uv run sphinx-build docs/source docs/build/html
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html
+          force_orphan: true

docs/Makefile

@@ -0,0 +1,42 @@
+# 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     = source
+BUILDDIR      = build
+
+SPHINXAPIDOC  = sphinx-apidoc
+SOURCEAPI     = source/api/
+BACKEND       = ../backend
+ALLAPIDOCOPTS = -e -M --tocfile backend --implicit-namespaces -o
+
+
+# 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)
+
+.PHONY: rst
+rst:
+	$(SPHINXAPIDOC) $(ALLAPIDOCOPTS) $(SOURCEAPI) $(BACKEND)
+	@echo
+	@echo "rst API documentation files generated. The .rst files are in $(SOURCEAPI)."
+
+.PHONY: rstf
+rstf:
+	$(SPHINXAPIDOC) -f $(ALLAPIDOCOPTS) $(SOURCEAPI) $(BACKEND)
+	@echo
+	@echo "rst API documentation files generated. The .rst files are in $(SOURCEAPI)."
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O);
+	cd build; git worktree add -f html gh-pages

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=source
+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/source/architecture.rst

@@ -0,0 +1,81 @@
+System Architecture
+===================
+
+This page explains the architecture of the system.
+It explains the overall structure of the backend and how the the backend interacts with the Celonis platform via `PyCelonis <https://celonis.github.io/pycelonis/2.13.0/>`_.
+
+Backend Architecture
+--------------------
+
+The overall backend architecture is shown in the following diagram:
+
+.. _backend-architecture:
+
+.. figure:: ./_static/img/backend.svg
+
+  Backend Architecture
+
+In the following, we explain the key components of the backend.
+
+Celonis Connection
+^^^^^^^^^^^^^^^^^^
+The :py:mod:`celonis_connection_manager <backend.celonis_connection.celonis_connection_manager>` module houses the :py:class:`CelonisConnectionManager <backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager>` class.
+This class is responsible for managing the connection to the Celonis platform.
+For this it uses the `PyCelonis <https://celonis.github.io/pycelonis/2.13.0/>`_ library to connect.
+
+It offers mechanisms to upload event logs to the Celonis platform, and run arbitrary PQL queries on the platform against the uploaded data.
+In the :py:mod:`API <backend.api>` module, we use this class as a dependency to connect to Celonis.
+This is done in the :py:mod:`celonis <backend.api.celonis>` module.
+
+Conformance Checking
+^^^^^^^^^^^^^^^^^^^^
+
+The :py:mod:`conformance_checking <backend.conformance_checking>` package contains modules for the four different conformance checking techniques.
+Each module defines a class that implements the conformance checking technique.
+These implementations are based on `PM4Py <https://processintelligence.solutions/pm4py>`_.
+
+These were built in a first iteration of the application.
+The application also allows to run the conformance techniques based on **PQL queries** instead of the PM4Py implementations.
+
+PQL Queries
+^^^^^^^^^^^
+
+The :py:mod:`pql_queries <backend.pql_queries>` package contains modules that define the PQL queries for the conformance checking techniques.
+As :ref:`backend-architecture` shows this package mirrors the strucuture of the :py:mod:`conformance_checking <backend.conformance_checking>` package.
+
+Each module defines PQL queries that can be used to run the conformance checking techniques on the Celonis platform.
+
+API
+^^^
+
+The :py:mod:`API <backend.api>` package contains the API endpoints for the application.
+It is probably the biggest package in the backend.
+It houses all the API relevant code.
+
+The backend API is built using the `FastAPI <https://fastapi.tiangolo.com/>`_ framework.
+The main application is defined in the :py:mod:`main <backend.api.main>` module.
+
+The API endpoints are split-up into different routers, each responsible for a specific functionality.
+The routers have the following functionality:
+
+* :py:mod:`setup <backend.api.setup>`: Contains endpoints for setting up the application, such as inserting Celonis credentials.
+* :py:mod:`log <backend.api.log>`: Contains endpoints for uploading event logs to the application and commiting them to the Celonis platform.
+* :py:mod:`jobs <backend.api.jobs>`: Contains endpoints for getting the status of jobs for conformance checking techniques.
+* :py:mod:`modules <backend.api.modules>`: Contains a module each, which defines a router, for each conformance checking technique.
+  These routers contain endpoints for running the conformance checking techniques and getting the results.
+
+Remaining Modules
+^^^^^^^^^^^^^^^^^
+
+The remaining modules in the backend contain code for various utilities and configurations.
+All modules are well documented and we refer the reader to the code itself and the :doc:`autoapi/index` for more details.
+
+Interaction with Celonis
+------------------------
+
+All conformance checking techniques use the Celonis platform to store the event logs.
+The basic implementations that are based on `PM4Py <https://processintelligence.solutions/pm4py>`_ (see :py:mod:`conformance_checking <backend.conformance_checking>`) download a basic variant of the event log from the Celonis platform.
+They then run all the conformance checking locally using PM4Py.
+
+The PQL-based implementations (see :py:mod:`pql_queries <backend.pql_queries>`) perform pre-computations on the event logs on the Celonis platform using `PQL <https://docs.celonis.com/en/pql---process-query-language.html>`_.
+They then fetch the results of these pre-computations and process them locally to compute the wanted results.

docs/source/autoapi/backend/api/celonis/index.rst

@@ -0,0 +1,87 @@
+backend.api.celonis
+===================
+
+.. py:module:: backend.api.celonis
+
+.. autoapi-nested-parse::
+
+   Contains the dependency injection for the CelonisConnectionManager.
+
+   This module contains one function, which is used to return a
+   CelonisConnectionManager instance. The function is used as a dependency
+   in the FastAPI application.
+
+
+
+Classes
+-------
+
+.. autoapisummary::
+
+   backend.api.celonis.CelonisSettings
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   backend.api.celonis.get_celonis_connection
+
+
+Module Contents
+---------------
+
+.. py:class:: CelonisSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: pydantic_settings.sources.DotenvType | None = ENV_FILE_SENTINEL, _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, Ellipsis] | None = None, _cli_settings_source: pydantic_settings.sources.CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: pydantic_settings.sources.PathType | None = None, **values: Any)
+
+   Bases: :py:obj:`pydantic_settings.BaseSettings`
+
+
+   Settings for the Celonis connection.
+
+   This class is used to load the Celonis connection settings from the
+   environment variables. The settings are loaded from a .env file
+   using the `pydantic_settings` library. The settings include the
+   Celonis base URL, data pool name, data model name, and API token.
+
+
+   .. py:attribute:: CELONIS_BASE_URL
+      :type:  str
+
+
+   .. py:attribute:: CELONIS_DATA_POOL_NAME
+      :type:  str
+
+
+   .. py:attribute:: CELONIS_DATA_MODEL_NAME
+      :type:  str
+
+
+   .. py:attribute:: API_TOKEN
+      :type:  str
+
+
+   .. py:attribute:: model_config
+
+      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].
+
+
+.. py:function:: get_celonis_connection(request: fastapi.Request) -> backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager
+
+   Returns a CelonisConnectionManager instance.
+
+   It tries to get the CelonisConnectionManager instance from the
+   application state. If it is not present, it creates a new instance
+   using the settings from the environment variables. The instance is
+   then stored in the application state for later use.
+   This function is used as a dependency in the FastAPI application.
+
+   :param request: The FastAPI request object. This is used to access the
+                   application state via `request.app.state`. The application state
+                   contains the `CelonisConnectionManager` instance, which is created
+                   during application startup and stored for later use.
+
+   :returns: The CelonisConnectionManager instance. This is used to connect to the
+             Celonis API and perform operations on the data pool.
+
+

docs/source/autoapi/backend/api/index.rst

@@ -0,0 +1,21 @@
+backend.api
+===========
+
+.. py:module:: backend.api
+
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   /autoapi/backend/api/celonis/index
+   /autoapi/backend/api/jobs/index
+   /autoapi/backend/api/log/index
+   /autoapi/backend/api/models/index
+   /autoapi/backend/api/modules/index
+   /autoapi/backend/api/setup/index
+   /autoapi/backend/api/tasks/index
+
+

docs/source/autoapi/backend/api/jobs/index.rst

@@ -0,0 +1,63 @@
+backend.api.jobs
+================
+
+.. py:module:: backend.api.jobs
+
+.. autoapi-nested-parse::
+
+   Contains the router for handling jobs.
+
+
+
+Attributes
+----------
+
+.. autoapisummary::
+
+   backend.api.jobs.router
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   backend.api.jobs.get_jobs
+   backend.api.jobs.verify_correct_job_module
+
+
+Module Contents
+---------------
+
+.. py:data:: router
+
+.. py:function:: get_jobs(job_id: str, request: fastapi.Request) -> backend.api.models.schemas.job_models.JobStatus
+   :async:
+
+
+   Fetches the status of a job via its ID.
+
+   :param job_id: The ID of the job to be fetched.
+   :param request: The FastAPI request object. This is used to access the
+                   application state via `request.app.state`.
+
+   :raises HTTPException: If the job with the given ID is not found in the
+   :raises application state.:
+
+   :returns: The status of the job as a JobStatus object.
+
+
+.. py:function:: verify_correct_job_module(job_id: str, request: fastapi.Request, module: str)
+
+   Verifies if a job belongs to the module.
+
+   Helper funciton used for the request of job states.
+
+   :param job_id: The ID of the job to be fetched.
+   :param request: The FastAPI request object. This is used to access the
+                   application state via `request.app.state`.
+   :param module: The name of the module that the job is checked against
+
+   :raises HTTPException: If the job with the given ID does not belong to the module
+
+