From 451a6de2b5fbdfa1bbf73afe7ef0fe99d9e27a7b Mon Sep 17 00:00:00 2001 From: Paula-Kli Date: Mon, 30 Oct 2023 11:29:51 +0100 Subject: [PATCH 1/2] docs: Enable prettier for docs again and fix issues --- .pre-commit-config.yaml | 1 - docs/docs/development/backend/exception.md | 29 +++--- docs/docs/development/backend/extensions.md | 47 +++++----- docs/docs/development/backend/technology.md | 3 +- docs/docs/development/frontend/routes.md | 30 ++++--- docs/docs/development/frontend/testing.md | 88 +++++++++---------- docs/docs/development/k8s/resources.md | 7 +- docs/docs/user/tokens.md | 9 +- .../user/tools/capella/working-with-git.md | 3 +- 9 files changed, 119 insertions(+), 98 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 03c911002..211a65adc 100644 --- a/.pre-commit-config.yaml +++ b/.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" diff --git a/docs/docs/development/backend/exception.md b/docs/docs/development/backend/exception.md index 2c2bf9333..3c7caf349 100644 --- a/docs/docs/development/backend/exception.md +++ b/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: -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: + +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. diff --git a/docs/docs/development/backend/extensions.md b/docs/docs/development/backend/extensions.md index 52cab0ce0..3a8b166b7 100644 --- a/docs/docs/development/backend/extensions.md +++ b/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:
@@ -29,27 +30,28 @@ 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` @@ -57,12 +59,13 @@ 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"] diff --git a/docs/docs/development/backend/technology.md b/docs/docs/development/backend/technology.md index 02a16e254..d136213b0 100644 --- a/docs/docs/development/backend/technology.md +++ b/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 diff --git a/docs/docs/development/frontend/routes.md b/docs/docs/development/frontend/routes.md index 445723acc..1250b0098 100644 --- a/docs/docs/development/frontend/routes.md +++ b/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`) diff --git a/docs/docs/development/frontend/testing.md b/docs/docs/development/frontend/testing.md index 5024622fa..5e13ead81 100644 --- a/docs/docs/development/frontend/testing.md +++ b/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=-` -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=-` 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=` -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=` 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 diff --git a/docs/docs/development/k8s/resources.md b/docs/docs/development/k8s/resources.md index 34a9dcbfc..82c5e5e8a 100644 --- a/docs/docs/development/k8s/resources.md +++ b/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 --sort cpu.limit --util --pods diff --git a/docs/docs/user/tokens.md b/docs/docs/user/tokens.md index f9789c40a..984f358e8 100644 --- a/docs/docs/user/tokens.md +++ b/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. diff --git a/docs/docs/user/tools/capella/working-with-git.md b/docs/docs/user/tools/capella/working-with-git.md index 402e76132..c150b5c47 100644 --- a/docs/docs/user/tools/capella/working-with-git.md +++ b/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. - - + !!! info Tick the box: "Import all existing Eclipse projects after clone finishes" importing the cloned repository into your eclipse workspace From 25b5cc7556be4319a8fe131470cbb85bd4c14667 Mon Sep 17 00:00:00 2001 From: Paula-Kli Date: Mon, 30 Oct 2023 16:30:16 +0100 Subject: [PATCH 2/2] docs: Use title case in menu --- docs/mkdocs.yml | 54 ++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 05857ab84..f510636ed 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -16,24 +16,24 @@ nav: - User documentation: - Introduction: user/index.md - Projects: - - Get access to a project: user/projects/access.md - - Add a user to a project: user/projects/add-user.md - - Request a new project: user/projects/create.md + - Get Access to a Project: user/projects/access.md + - Add a User to a Project: user/projects/add-user.md + - Request a New Project: user/projects/create.md - Roles: user/projects/roles.md - Models: - - Create a model: user/projects/models/create.md - - Update a model to a newer version: user/projects/models/update.md - - Update model metadata: user/projects/models/metadata.md - - Model sources: + - Create a Model: user/projects/models/create.md + - Update a Model to a Newer Version: user/projects/models/update.md + - Update Model Metadata: user/projects/models/metadata.md + - Model Sources: - TeamForCapella: user/projects/models/sources/t4c.md - Backups: - - Setup a model backup: user/projects/models/backups/setup.md - - Trigger a model backup: user/projects/models/backups/trigger.md - - Remove a model backup: user/projects/models/backups/remove.md + - Setup a Model Backup: user/projects/models/backups/setup.md + - Trigger a Model Backup: user/projects/models/backups/trigger.md + - Remove a Model Backup: user/projects/models/backups/remove.md - Diagram cache: - - Setup diagram cache: user/projects/models/diagrams/setup_diagram_cache.md - - View diagram cache: user/projects/models/diagrams/view_diagram_cache.md - - Model complexity badge: user/projects/models/complexity_badge.md + - Setup Diagram Cache: user/projects/models/diagrams/setup_diagram_cache.md + - View Diagram Cache: user/projects/models/diagrams/view_diagram_cache.md + - Model Complexity Badge: user/projects/models/complexity_badge.md - Sessions: - Session Types: - Overview: user/sessions/types.md @@ -46,7 +46,7 @@ nav: - Flows: - Git: user/sessions/flows/git.md - TeamForCapella: user/sessions/flows/t4c.md - - Files browser: user/sessions/files/files.md + - Files Browser: user/sessions/files/files.md - Troubleshooting: user/sessions/troubleshooting.md - Jupyter: - Collaboration: user/sessions/jupyter/collaboration.md @@ -59,21 +59,21 @@ nav: - Git: user/settings/model-sources/git.md - T4C: user/settings/model-sources/t4c.md - Alerts: - - Create an alert: user/alerts/create.md + - Create an Alert: user/alerts/create.md - Tools: - Capella: - Introduction: user/tools/capella/introduction.md - - Co-working methods: user/tools/capella/t4c-git-compare.md + - Co-working Methods: user/tools/capella/t4c-git-compare.md - TeamForCapella: - - Import a model from TeamForCapella: user/tools/capella/teamforcapella/import/import-from-t4c.md - - Export a model to TeamForCapella: user/tools/capella/teamforcapella/export/export-to-t4c.md - - TeamForCapella repository management: user/tools/capella/teamforcapella/repository-management.md + - Import a Model from TeamForCapella: user/tools/capella/teamforcapella/import/import-from-t4c.md + - Export a Model to TeamForCapella: user/tools/capella/teamforcapella/export/export-to-t4c.md + - TeamForCapella Repository Management: user/tools/capella/teamforcapella/repository-management.md - TeamForCapella Project Management: user/tools/capella/teamforcapella/project-management/project-management.md - - Update a TeamForCapella based model: user/tools/capella/teamforcapella/update.md + - Update a TeamForCapella-based Model: user/tools/capella/teamforcapella/update.md - Git: - Working with Git: user/tools/capella/working-with-git.md - Authentication: user/tokens.md - - Administrator documentation: + - Administrator Documentation: - Index: admin/index.md - Installation: admin/installation.md - Uninstallation: admin/uninstallation.md @@ -82,22 +82,22 @@ nav: - Gitlab CI/CD: - Image builder: admin/ci-templates/gitlab/image-builder.md - Kubernetes deployment: admin/ci-templates/gitlab/k8s-deploy.md - - Developer documentation: + - Developer Documentation: - Home: development/index.md - Backend: - Code Style: development/backend/code-style.md - - Technology overview: development/backend/technology.md - - Extension modules: development/backend/extensions.md - - Exception handling: development/backend/exception.md + - Technology Overview: development/backend/technology.md + - Extension Modules: development/backend/extensions.md + - Exception Handling: development/backend/exception.md - API Authentication: development/backend/authentication.md - - Database migration: development/backend/database-migration.md + - Database Migration: development/backend/database-migration.md - Frontend: - Code Style: development/frontend/code-style.md - Routes: development/frontend/routes.md - Testing: development/frontend/testing.md - Customization: development/frontend/customize.md - Kubernetes: - - Meassure resource usage: development/k8s/resources.md + - Measure Resource Usage: development/k8s/resources.md - Documentation: development/docs.md - Release Notes: release-notes.md