Merge pull request #1139 from DSD-DBS/update-docs

docs: Enable prettier for docs again and fix issues

.pre-commit-config.yaml

@@ -73,7 +73,6 @@ repos:
     hooks:
       - id: prettier
         types_or: [ts, css, html, markdown]
-        files: "^frontend"
         additional_dependencies:
           - "prettier@^3.0.3"
           - "prettier-plugin-tailwindcss@^0.5.5"

docs/docs/development/backend/exception.md

@@ -5,11 +5,11 @@
 
 # Exception Handling
 
-Various errors can occur in the backend,
-which must be made understandable to the end user and the developers
-when calling the API.
+Various errors can occur in the backend, which must be made understandable to
+the end user and the developers when calling the API.
 
-In general, please use the following syntax to return a error message from the backend:
+In general, please use the following syntax to return a error message from the
+backend:
 
 ```py title="routes.py"
 from fastapi import HTTPException
@@ -28,9 +28,18 @@ raise HTTPException(
 )
 ```
 
-1. Please use the corresponding HTTP response status code here. More information about status codes: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status>
-1. _Optional_: Unique error code (as string). Can be evaluated in the frontend to identify a specific error.
-1. _Optional_: Use a title that is automatically displayed in the frontend (only works when the `reason` parameter is provided).
-1. _Optional_: Use a message that is automatically displayed in the frontend for users.
-   Since the message will be displayed to end users, it should contain context for classification and should be user-friendly (not technical!)
-1. _Optional_: Technical message for developers, not displayed in the frontend. Is part of the error response json.
+## Important Hints for Exceptions
+
+1. Please use the corresponding HTTP response status code here. More
+   information about status codes:
+   <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status>
+1. _Optional_: Unique error code (as string). Can be evaluated in the frontend
+   to identify a specific error.
+1. _Optional_: Use a title that is automatically displayed in the frontend
+   (only works when the `reason` parameter is provided).
+1. _Optional_: Use a message that is automatically displayed in the frontend
+   for users. Since the message will be displayed to end users, it should
+   contain context for classification and should be user-friendly (not
+   technical!)
+1. _Optional_: Technical message for developers, not displayed in the frontend.
+   Is part of the error response json.

docs/docs/development/backend/extensions.md

@@ -3,9 +3,10 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-In order to make the whole backend more consistent, it is divided into different modules.
-This is intended to ensure that these are outsourced easily and without major effects
-and that other modules can also be easily added as "plugins", e.g., via [Python entrypoints]
+In order to make the whole backend more consistent, it is divided into
+different modules. This is intended to ensure that these are outsourced easily
+and without major effects and that other modules can also be easily added as
+"plugins", e.g., via [Python entrypoints]
 
 A extension has the following structure: <br>
 
@@ -29,40 +30,42 @@ Code to be called to initialize a module.
 
 ### `crud.py`
 
-All `CRUD` (Create, read, update and delete) related operations.
-They should be used to access the database. They should be used
-to access the database, in case there are no existing injectables.
+All `CRUD` (Create, read, update and delete) related operations. They should be
+used to access the database. They should be used to access the database, in
+case there are no existing injectables.
 
-There should not be much logic in the `crud.py` files
-(really just creating, reading, updating and deleting) models in the database.
+There should not be much logic in the `crud.py` files (really just creating,
+reading, updating and deleting) models in the database.
 
 ### `injectables.py`
 
-In the `injectables` module, we define useful functions that allow to
-retrieve resources by simply defining the resource as parameter of the
-fastapi route and using the injectable function as dependency (i.e.,
-`resource: ResourceType = Depends(injectableFunction)`).
-By using these injectables, we reduce the code duplication, since we
-include logic (such as checking whether a project exists) into the
-injectable function, and the readability of the code is increased.
+In the `injectables` module, we define useful functions that allow to retrieve
+resources by simply defining the resource as parameter of the fastapi route and
+using the injectable function as dependency (i.e.,
+`resource: ResourceType = Depends(injectableFunction)`). By using these
+injectables, we reduce the code duplication, since we include logic (such as
+checking whether a project exists) into the injectable function, and the
+readability of the code is increased.
 
 ### `models.py`
 
-In the `models` module, all `pydantic` and `SQLAlchemy` models should be defined.
-In general, we use the `Database` prefix for `SQLAlchemy` models, e.g., `DatabaseProject`.
+In the `models` module, all `pydantic` and `SQLAlchemy` models should be
+defined. In general, we use the `Database` prefix for `SQLAlchemy` models,
+e.g., `DatabaseProject`.
 
 ### `routes.py`
 
 The `routes` module should include all fastAPI routes.
 
 ### `...`
 
-Other submodules can of course be created and are usually also useful if logic needs to be implemented.
+Other submodules can of course be created and are usually also useful if logic
+needs to be implemented.
 
 ## Entrypoints
 
-Core modules are directly imported in the code. However, for modules that change
-frequently or should be interchangeable, we use Python entrypoints.
+Core modules are directly imported in the code. However, for modules that
+change frequently or should be interchangeable, we use [Python entrypoints].
 
 A entrypoint can be defined in the `pyproject.toml` file:
 
@@ -72,8 +75,8 @@ extension1 = "path.to.extension1"
 extension2 = "path.to.extension2"
 ```
 
-The `routes` and `models` components are then imported in the code:
-For example, to include the routers, we use the following code:
+The `routes` and `models` components are then imported in the code: For
+example, to include the routers, we use the following code:
 
 ```py title="routes.py"
 eps = metadata.entry_points()["capellacollab.extensions"]

docs/docs/development/backend/technology.md

@@ -3,8 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-We use some different libraries in the backend.
-Here is a quick overview.
+We use some different libraries in the backend. Here is a quick overview.
 
 ## FastAPI
 

docs/docs/development/frontend/routes.md

@@ -5,26 +5,36 @@
 
 # Frontend Routes
 
-For consistency, we have a strict structure for our frontend route URIs.
-The structure is based on REST, but not completely the same due to the limitations of the unavailable request methods.
-
-- `/resources` for the resource overview, e.g., `/projects` for the projects overview
-- `/resources/action` for a specific action (not related to a specific instance of the resource), e.g., `/projects/create` to create a project. Possible actions are:
+For consistency, we have a strict structure for our frontend route URIs. The
+structure is based on REST, but not completely the same due to the limitations
+of the unavailable request methods.
+
+- `/resources` for the resource overview, e.g., `/projects` for the projects
+  overview
+- `/resources/action` for a specific action (not related to a specific instance
+  of the resource), e.g., `/projects/create` to create a project. Possible
+  actions are:
   - `create`
   - `delete`
-  - or any other action if the action is not used to `create` or `delete` a resource.
-- `/resources/action/subaction` for a specific action related to a parent action, e.g., `/project/:name/models/create/source` to go to the source stage of the model creation.
+  - or any other action if the action is not used to `create` or `delete` a
+    resource.
+- `/resources/action/subaction` for a specific action related to a parent
+  action, e.g., `/project/:name/models/create/source` to go to the source stage
+  of the model creation.
 - `resource/:name` to access a single instance of type resource.
-- `resource/:name/childresource` to access a single child resource of a specific instance from type resource.
+- `resource/:name/childresource` to access a single child resource of a
+  specific instance from type resource.
 
 ## Examples
 
 Valid routes are:
 
-- `/project/test/models/create` is a valid route to create a model in the project `test`.
+- `/project/test/models/create` is a valid route to create a model in the
+  project `test`.
 - `/projects` is a valid route for the overview of projects.
 
 These are not valid:
 
 - `/project/create` (`project` should be plural)
-- `/models` (`models` is a child resource of `projects`, therefore it should be `/projects/:id/models`)
+- `/models` (`models` is a child resource of `projects`, therefore it should be
+  `/projects/:id/models`)

docs/docs/development/frontend/testing.md

@@ -5,11 +5,12 @@
 
 # Frontend Testing
 
-**Note:** While frontend testing is valuable, the process of writing and maintaining
-such tests can be challenging and time-consuming in certain instances. Therefore,
-our team does not require frontend tests for every component or service.
-Please ensure that ".spec" files are only included if they have active tests.
-Before writing tests, consider the overhead and weigh it against the potential benefits.
+**Note:** While frontend testing is valuable, the process of writing and
+maintaining such tests can be challenging and time-consuming in certain
+instances. Therefore, our team does not require frontend tests for every
+component or service. Please ensure that ".spec" files are only included if
+they have active tests. Before writing tests, consider the overhead and weigh
+it against the potential benefits.
 
 ## Unit & Integration Testing
 
@@ -28,32 +29,31 @@ Before writing tests, consider the overhead and weigh it against the potential b
 
 #### Robust Component Tests
 
-When testing components, we must query the elements needed for the test.
-To ensure that even if the element type or attributes changes, the element
-can still be queried, we assign a `data-testId` to each needed element.
-This not only increases robustness, but also makes it very easy
-to query elements. The value assigned to the test id should clearly describe
-the usage of the element and should not be too long.
-For example, one can use the schema `data-testId=<type>-<description>`
-where the prefix usually describes the general contex (e.g., whether it is
-an input, button, textfield, etc.) and the following description specifies the
-usage of it (e.g., createProject).
+When testing components, we must query the elements needed for the test. To
+ensure that even if the element type or attributes changes, the element can
+still be queried, we assign a `data-testId` to each needed element. This not
+only increases robustness, but also makes it very easy to query elements. The
+value assigned to the test id should clearly describe the usage of the element
+and should not be too long. For example, one can use the schema
+`data-testId=<type>-<description>` where the prefix usually describes the
+general contex (e.g., whether it is an input, button, textfield, etc.) and the
+following description specifies the usage of it (e.g., createProject).
 
 #### Element Helper Functions
 
-Usually testing components consists of querying elements, applying changes
-to them, triggering events on them, and then comparing the results with the
-expected results. To reduce repetition and increase readability, one should
-use existing helper functions or create new ones if none exist.
+Usually testing components consists of querying elements, applying changes to
+them, triggering events on them, and then comparing the results with the
+expected results. To reduce repetition and increase readability, one should use
+existing helper functions or create new ones if none exist.
 
 ### Executing Tests
 
-To execute the integration tests, one needs to run `make test`. However, in some
-cases it is not possible to correctly set the `CHROME_BIN` that is needed to generate
-the test output inside the browser. If this is the case, one should either set
-the `CHORME_BIN` in the make file or simply run `EXPORT CHROME_BIN=<path>`
-followed by `ng test`. Beyond that, it is not necessary to run anything else
-(e.g., the backend) for test execution.
+To execute the integration tests, one needs to run `make test`. However, in
+some cases it is not possible to correctly set the `CHROME_BIN` that is needed
+to generate the test output inside the browser. If this is the case, one should
+either set the `CHORME_BIN` in the make file or simply run
+`EXPORT CHROME_BIN=<path>` followed by `ng test`. Beyond that, it is not
+necessary to run anything else (e.g., the backend) for test execution.
 
 #### Output
 
@@ -63,9 +63,9 @@ The resulting output in the browser considers three different cases:
 2. Yellow tests (marked with a ☆) are _deactivated_ tests
 3. Red tests are _failed_ tests
 
-The general code coverage statistics (i.e. statement, branch, function,
-and line coverage) are output to the console. To also see what exactly is
-covered and what is missing, one can open the `index.html` file in the
+The general code coverage statistics (i.e. statement, branch, function, and
+line coverage) are output to the console. To also see what exactly is covered
+and what is missing, one can open the `index.html` file in the
 `/frontend/test-results/istanbul-coverage` folder.
 
 ## End-to-End Testing
@@ -76,26 +76,26 @@ covered and what is missing, one can open the `index.html` file in the
 
 ### Test Generation
 
-Playwright supports the generation of E2E tests by interacting
-with the frontend and recording each action and input. This can be started
-by executing `npx playwright codegen localhost:4200` but needs a running
-frontend and backend to work.
+Playwright supports the generation of E2E tests by interacting with the
+frontend and recording each action and input. This can be started by executing
+`npx playwright codegen localhost:4200` but needs a running frontend and
+backend to work.
 
-Test generation can significantly speed up test creation, but in general
-one should only use the resulting test as a base and adjust it accordingly.
-For example, check selectors and adjust them to make them more robust,
-or add more expectations as needed.
+Test generation can significantly speed up test creation, but in general one
+should only use the resulting test as a base and adjust it accordingly. For
+example, check selectors and adjust them to make them more robust, or add more
+expectations as needed.
 
 ### Executing Tests
 
-To run the E2E tests, one must first make sure that a backend is running.
-If that is the case, one can run `npx playwright test` to start
-the tests. In case of an error the browser will be directly opened and
-show the last test report, otherwise one can open it with `npx playwright show-report`.
-A very helpful option when running the tests is `--trace on`. This provides,
-for example, a screenshot of the action and the before/after state (for each step),
-contains a detailed log, and one can also view the console output and
-network calls performed.
+To run the E2E tests, one must first make sure that a backend is running. If
+that is the case, one can run `npx playwright test` to start the tests. In case
+of an error the browser will be directly opened and show the last test report,
+otherwise one can open it with `npx playwright show-report`. A very helpful
+option when running the tests is `--trace on`. This provides, for example, a
+screenshot of the action and the before/after state (for each step), contains a
+detailed log, and one can also view the console output and network calls
+performed.
 
 [jasmine]: https://jasmine.github.io
 [karma]: https://karma-runner.github.io

docs/docs/development/k8s/resources.md

@@ -3,14 +3,15 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-To find out which resources are used in the cluster, you can install a
-the tool [`kube-capacity`](https://github.com/robscott/kube-capacity):
+To find out which resources are used in the cluster, you can install a the tool
+[`kube-capacity`](https://github.com/robscott/kube-capacity):
 
 ```zsh
 kubectl krew install resource-capacity
 ```
 
-When the installation is complete, you can see an overview over the resources in your namespace:
+When the installation is complete, you can see an overview over the resources
+in your namespace:
 
 ```zsh
 kubectl resource-capacity -n <NAMESPACE> --sort cpu.limit --util --pods

docs/docs/user/tokens.md

@@ -42,9 +42,9 @@ authenticate with that against the Collaboration Manager API. One example is:
 curl -u [username]:[token] https://[baseURL]/api/v1/projects
 ```
 
-Another example is working with the diagram cache of py-capellambse.
-The implementation of the capella modelling tool `capellambse` uses Python and lets you read and
-write models. For more information have a look at the
+Another example is working with the diagram cache of py-capellambse. The
+implementation of the capella modelling tool `capellambse` uses Python and lets
+you read and write models. For more information have a look at the
 [documentation](https://dsd-dbs.github.io/py-capellambse/) or the
 [Github repository](https://github.com/DSD-DBS/py-capellambse).
 
@@ -59,4 +59,5 @@ model = capellambse.model.MelodyModel(
 )
 ```
 
-Having created a model like that you can e.g. with `model.diagrams[0]` get the first diagram.
+Having created a model like that you can e.g. with `model.diagrams[0]` get the
+first diagram.

docs/docs/user/tools/capella/working-with-git.md

@@ -28,8 +28,7 @@ clicking "Next" the "Branch Selection" opens. Here you can pick a branch on
 which you want to work. After clicking "Next" another time, the view "Local
 Destination" opens. This shows where your work is going to be stored locally.
 
- <!-- prettier-ignore -->
-
+<!-- prettier-ignore -->
 !!! info
     Tick the box: "Import all existing Eclipse projects after clone
     finishes" importing the cloned repository into your eclipse workspace