From af7dae9469c05718b59a97e79cb773131e791d75 Mon Sep 17 00:00:00 2001 From: MoritzWeber Date: Mon, 12 Aug 2024 16:00:48 +0200 Subject: [PATCH] refactor(docs): Use indentation of 4 instead of 2 This will fix some issues regarding the rendering of lists and seems to be more compatible with the prettier formatting. With the change I could remove some `prettier-ignore` messages. --- docs/.prettierrc.yaml | 10 ++ .../ci-templates/gitlab/image-builder.md | 32 ++--- .../admin/ci-templates/gitlab/k8s-deploy.md | 32 ++--- docs/docs/admin/getting_started/index.md | 6 +- docs/docs/admin/installation.md | 37 ++--- docs/docs/admin/settings/model-sources/git.md | 46 +++--- docs/docs/admin/settings/tools/index.md | 4 +- .../project-management/index.md | 16 +-- docs/docs/admin/tools/configuration.md | 88 ++++++------ docs/docs/api/index.md | 12 +- docs/docs/development/backend/code-style.md | 131 +++++++++--------- docs/docs/development/docs.md | 6 +- docs/docs/development/frontend/customize.md | 2 +- .../frontend/responsive-design/mobile-view.md | 36 ++--- docs/docs/development/frontend/routes.md | 42 +++--- docs/docs/development/frontend/storybook.md | 10 +- docs/docs/development/frontend/testing.md | 12 +- docs/docs/development/index.md | 22 +-- docs/docs/development/pull_requests.md | 53 +++---- docs/docs/development/troubleshooting.md | 20 +-- docs/docs/index.md | 16 +-- docs/docs/release-notes.md | 33 +++-- docs/docs/user/index.md | 80 +++++------ docs/docs/user/projects/add-user/index.md | 13 +- .../user/projects/models/complexity_badge.md | 4 +- docs/docs/user/projects/models/create.md | 8 +- .../models/diagrams/setup_diagram_cache.md | 4 +- .../user/sessions/jupyter/collaboration.md | 4 +- .../user/tools/capella/t4c-git-compare.md | 41 +++--- 29 files changed, 421 insertions(+), 399 deletions(-) create mode 100644 docs/.prettierrc.yaml diff --git a/docs/.prettierrc.yaml b/docs/.prettierrc.yaml new file mode 100644 index 000000000..96ef215a7 --- /dev/null +++ b/docs/.prettierrc.yaml @@ -0,0 +1,10 @@ +# SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +# SPDX-License-Identifier: Apache-2.0 + +singleQuote: true +overrides: + - files: '*.md' + options: + tabWidth: 4 + proseWrap: always + printWidth: 79 diff --git a/docs/docs/admin/ci-templates/gitlab/image-builder.md b/docs/docs/admin/ci-templates/gitlab/image-builder.md index e6ed8fd8b..1337f7759 100644 --- a/docs/docs/admin/ci-templates/gitlab/image-builder.md +++ b/docs/docs/admin/ci-templates/gitlab/image-builder.md @@ -12,7 +12,7 @@ Please add the following section to your `.gitlab-ci.yml`: ```yaml include: - - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/image-builder.yml + - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/image-builder.yml ``` The build images are tagged with the revision they were build with (e.g., when @@ -22,13 +22,13 @@ running for main the tag would be `:main`). All characters matching the regex You have to add the following environment variables on repository level. Make sure to enable the "Expand variable reference" flag. -- `PRIVATE_GPG_PATH`: Path to the private GPG key used to decrypt the - `secret.docker.json` file (More about this file [below](#docker-sops-file)) -- Variables specifying how to name each image: - - `FRONTEND_IMAGE_NAME` (defaults to `capella/collab/frontend`) - - `BACKEND_IMAGE_NAME` (default to `capella/collab/backend`) - - `DOCS_IMAGE_NAME` (defaults to `capella/collab/docs`) - - `GUACAMOLE_IMAGE_NAME` (defaults to `capella/collab/guacamole`) +- `PRIVATE_GPG_PATH`: Path to the private GPG key used to decrypt the + `secret.docker.json` file (More about this file [below](#docker-sops-file)) +- Variables specifying how to name each image: + - `FRONTEND_IMAGE_NAME` (defaults to `capella/collab/frontend`) + - `BACKEND_IMAGE_NAME` (default to `capella/collab/backend`) + - `DOCS_IMAGE_NAME` (defaults to `capella/collab/docs`) + - `GUACAMOLE_IMAGE_NAME` (defaults to `capella/collab/guacamole`) This is the (minimal) configuration. For more advanced configuration options, please refer to the @@ -45,11 +45,11 @@ following structure: ```yaml creation_rules: - - path_regex: .* - encrypted_regex: ^(password|secret|adminPassword|uri|token) - key_groups: - - pgp: - - + - path_regex: .* + encrypted_regex: ^(password|secret|adminPassword|uri|token) + key_groups: + - pgp: + - ``` Ensure that the GPG fingerprint of the Gitlab runner is present in the @@ -67,9 +67,9 @@ Then, enter the following content: ```json { - "registry": "", - "username": "", - "password": "" + "registry": "", + "username": "", + "password": "" } ``` diff --git a/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md b/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md index 7564ae60f..895833db0 100644 --- a/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md +++ b/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md @@ -12,17 +12,17 @@ Please add the following section to your `.gitlab-ci.yml`: ```yaml include: - - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/k8s-deploy.yml + - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/k8s-deploy.yml ``` You have to add the following environment variables on repository level. Make sure to enable the "Expand variable reference" flag. -- `PRIVATE_GPG_PATH`: Path to the private GPG key used to decrypt the - `secret.k8s.json` files. -- `GRAFANA_HELM_CHART`: (Optional) - This variable is used to set the URL for - the Grafana Helm chart. It is useful if your deployment environment has - limited access, so you can specify a URL that is accessible for you. +- `PRIVATE_GPG_PATH`: Path to the private GPG key used to decrypt the + `secret.k8s.json` files. +- `GRAFANA_HELM_CHART`: (Optional) - This variable is used to set the URL for + the Grafana Helm chart. It is useful if your deployment environment has + limited access, so you can specify a URL that is accessible for you. ## SOPS configuration @@ -34,11 +34,11 @@ following structure: ```yaml creation_rules: - - path_regex: .* - encrypted_regex: ^(password|secret|adminPassword|uri|token) - key_groups: - - pgp: - - + - path_regex: .* + encrypted_regex: ^(password|secret|adminPassword|uri|token) + key_groups: + - pgp: + - ``` Ensure that the GPG fingerprint of the Gitlab runner is present in the @@ -56,11 +56,11 @@ The file has to contain the following content: ```json { - "server": "", - "namespace": "", - "release": "", - "username": "", - "token": "" + "server": "", + "namespace": "", + "release": "", + "username": "", + "token": "" } ``` diff --git a/docs/docs/admin/getting_started/index.md b/docs/docs/admin/getting_started/index.md index 8b145988c..e776ede85 100644 --- a/docs/docs/admin/getting_started/index.md +++ b/docs/docs/admin/getting_started/index.md @@ -47,6 +47,6 @@ Collaboration Manager. More advanced features include: -- Read-only models from Git -- Connect to a Team4Capella server (commercial product) -- Manage users and user access +- Read-only models from Git +- Connect to a Team4Capella server (commercial product) +- Manage users and user access diff --git a/docs/docs/admin/installation.md b/docs/docs/admin/installation.md index 6b71b012d..987b96d97 100644 --- a/docs/docs/admin/installation.md +++ b/docs/docs/admin/installation.md @@ -109,21 +109,24 @@ of memory. The Collaboration Manager requires two different namespaces. For security and overview reasons, they are separated: - -- Capella Collaboration Manager control namespace: In this namespace, we run - the core application. It has full control over the sessions namespace and consists of the following services: - - Frontend - - Backend - - Documentation - - Guacamole - - Prometheus - - Grafana (Loki), can be disabled in the `values.yaml` - -- Sessions namespace. The namespace is controlled by the control namespace and you won't need to touch it. In the session namespace, the following services run: - - Storage for persistent workspaces - - Storage for Juypter file-shares - - Pipeline jobs for nightly TeamForCapella to Git synchronisation - - Session containers (Capella, Papyrus, Juypter, pure::variants) +- Capella Collaboration Manager control namespace: In this namespace, we run + the core application. It has full control over the sessions namespace and + consists of the following services: + + - Frontend + - Backend + - Documentation + - Guacamole + - Prometheus + - Grafana (Loki), can be disabled in the `values.yaml` + +- Sessions namespace. The namespace is controlled by the control namespace + and you won't need to touch it. In the session namespace, the following + services run: + - Storage for persistent workspaces + - Storage for Juypter file-shares + - Pipeline jobs for nightly TeamForCapella to Git synchronisation + - Session containers (Capella, Papyrus, Juypter, pure::variants) --- @@ -261,8 +264,8 @@ If a value is false, check the backend logs for more information. Capella Docker images documentation (Only the preparation section is needed): - - [`capella/base`](https://dsd-dbs.github.io/capella-dockerimages/capella/base/#preparation) - - [`t4c/client/base`](https://dsd-dbs.github.io/capella-dockerimages/capella/t4c/base/#preparation) + - [`capella/base`](https://dsd-dbs.github.io/capella-dockerimages/capella/base/#preparation) + - [`t4c/client/base`](https://dsd-dbs.github.io/capella-dockerimages/capella/t4c/base/#preparation) 1. Set the following environment variables: diff --git a/docs/docs/admin/settings/model-sources/git.md b/docs/docs/admin/settings/model-sources/git.md index 7a4d00048..36f926cef 100644 --- a/docs/docs/admin/settings/model-sources/git.md +++ b/docs/docs/admin/settings/model-sources/git.md @@ -22,27 +22,27 @@ Gitlab, are not available. please use the form below "Add new integration". You have to enter the following information: - 1. **Git Type** - - **General**: Works with every - [Git server](https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server) - that supports the Git protocol. Features like the diagram cache are not - available. - - **Gitlab**: Only works with [Gitlab](https://about.gitlab.com/) - instances (self-hosted / SaaS). With Gitlab, the diagram cache - integration can be used. - - **Github**: Works with the public [Github](https://github.com/) - instance. With Github, the diagram cache integration can be used. - 1. **Name**: Any name to identify the instance - 1. **Instance base URL**: The base URL of the instance, e.g., - `https://gitlab.com`. For more information, see - [Matching between models and instances](#matching-between-models-and-instances) - 1. **API URL**: - - **Gitlab**: The API URL to the - [Gitlab REST API](https://docs.gitlab.com/ee/api/rest/). In most of the - cases: `{base_url}/api/v4`, e.g., `https://gitlab.com/api/v4`. - - **Github**: The API URL to the - [Github REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28). - The url is `https://api.github.com`. + 1. **Git Type** + - **General**: Works with every + [Git server](https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server) + that supports the Git protocol. Features like the diagram cache are + not available. + - **Gitlab**: Only works with [Gitlab](https://about.gitlab.com/) + instances (self-hosted / SaaS). With Gitlab, the diagram cache + integration can be used. + - **Github**: Works with the public [Github](https://github.com/) + instance. With Github, the diagram cache integration can be used. + 1. **Name**: Any name to identify the instance + 1. **Instance base URL**: The base URL of the instance, e.g., + `https://gitlab.com`. For more information, see + [Matching between models and instances](#matching-between-models-and-instances) + 1. **API URL**: + - **Gitlab**: The API URL to the + [Gitlab REST API](https://docs.gitlab.com/ee/api/rest/). In most of + the cases: `{base_url}/api/v4`, e.g., `https://gitlab.com/api/v4`. + - **Github**: The API URL to the + [Github REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28). + The url is `https://api.github.com`. !!! warning @@ -55,8 +55,8 @@ Models are matched with instances with a longest prefix match of the URL. Let's construct a short example. We have two Git instances: -- Instance one with the URL `https://git.example.com/` -- Instance two with the URL `https://git.example.com/test` +- Instance one with the URL `https://git.example.com/` +- Instance two with the URL `https://git.example.com/test` A model with the path `https://git.example.com/test/test2.git` is now associated with instance two. A model with the path diff --git a/docs/docs/admin/settings/tools/index.md b/docs/docs/admin/settings/tools/index.md index 40050d27e..1b3e84957 100644 --- a/docs/docs/admin/settings/tools/index.md +++ b/docs/docs/admin/settings/tools/index.md @@ -16,8 +16,8 @@ can be used as a web-based tool. Tools can be found in various places on the platform: -- Models in projects are always assigned to a specific tool. -- Sessions are always started for a specific tool. +- Models in projects are always assigned to a specific tool. +- Sessions are always started for a specific tool. Each tool has different versions and natures, which can be configured individually. Since different versions can be enabled in parallel, it helps to diff --git a/docs/docs/admin/teamforcapella/project-management/index.md b/docs/docs/admin/teamforcapella/project-management/index.md index 2cba410ce..aeb4745b1 100644 --- a/docs/docs/admin/teamforcapella/project-management/index.md +++ b/docs/docs/admin/teamforcapella/project-management/index.md @@ -34,14 +34,14 @@ guide. 1. Enter the connection string for the TeamForCapella server. There two ways to find the correct one. Make sure that the host is prefixed with `tcp://`. - 1. Global administrators can navigate to `Menu` > `Settings` > - `Model sources` > `TeamForCapella` > Select the instance > `Host`. - 1. Project managers can use the TeamForCapella connection flow described in - the - [Connect to a TeamForCapella repository](../../../user/tools/capella/teamforcapella/export/index.md) - guide. In the `Connect to Shared Project` dialog, select the repository, - expand "Connection information" and copy the "Repository host". - ![Find out T4C server host](./find-out-repository-host.png) + 1. Global administrators can navigate to `Menu` > `Settings` > + `Model sources` > `TeamForCapella` > Select the instance > `Host`. + 1. Project managers can use the TeamForCapella connection flow described in + the + [Connect to a TeamForCapella repository](../../../user/tools/capella/teamforcapella/export/index.md) + guide. In the `Connect to Shared Project` dialog, select the repository, + expand "Connection information" and copy the "Repository host". + ![Find out T4C server host](./find-out-repository-host.png) 1. Enter the repository name and confirm with "Ok". ![Open CDO session](./open-cdo-session.png) diff --git a/docs/docs/admin/tools/configuration.md b/docs/docs/admin/tools/configuration.md index d33c2eb15..77659c9e8 100644 --- a/docs/docs/admin/tools/configuration.md +++ b/docs/docs/admin/tools/configuration.md @@ -10,20 +10,20 @@ To add a tool to the Collaboration Manager, it must fulfill the following requirements: -- The tool must run in a single Docker container (no sidecar containers). -- The Docker container has to run with a non-root user. -- The Docker image has to be deployed to a Docker registry, which is accessible - from the Collaboration Manager server environment. -- The tool must be exposed via RDP or HTTP/HTTPS. -- If the tool is exposed via RDP, it must accept basic authentication. For - HTTP-based tools, authentication is handled automatically via - pre-authentication. -- The container must expose a `/metrics` endpoint with an `idletime_minutes` - gauge metric in the OpenMetrics format, which returns the time in minutes - since the last user interaction. The metric is used to determine if the - session is idle and can be terminated. -- If you want to capture session logs and make them accessible via Grafana - Loki, they have to be written to disk (stdout/stderr are not persisted). +- The tool must run in a single Docker container (no sidecar containers). +- The Docker container has to run with a non-root user. +- The Docker image has to be deployed to a Docker registry, which is + accessible from the Collaboration Manager server environment. +- The tool must be exposed via RDP or HTTP/HTTPS. +- If the tool is exposed via RDP, it must accept basic authentication. For + HTTP-based tools, authentication is handled automatically via + pre-authentication. +- The container must expose a `/metrics` endpoint with an `idletime_minutes` + gauge metric in the OpenMetrics format, which returns the time in minutes + since the last user interaction. The metric is used to determine if the + session is idle and can be terminated. +- If you want to capture session logs and make them accessible via Grafana + Loki, they have to be written to disk (stdout/stderr are not persisted). ## YAML Configuration @@ -39,12 +39,12 @@ An example configuration looks like this: ```yaml resources: - cpu: - requests: 0.4 - limits: 2 - memory: - requests: 1.6Gi - limits: 6Gi + cpu: + requests: 0.4 + limits: 2 + memory: + requests: 1.6Gi + limits: 6Gi ``` The values are Kubernetes resource requests and limits. More information is @@ -238,7 +238,7 @@ A variable is defined in the tool configuration: ```yaml environment: - MY_TOOL_USERNAME_WITH_PREFIX: 'test_{CAPELLACOLLAB_SESSION_REQUESTER_USERNAME}' + MY_TOOL_USERNAME_WITH_PREFIX: 'test_{CAPELLACOLLAB_SESSION_REQUESTER_USERNAME}' ``` In this example, we map the `MY_TOOL_USERNAME` variable to the @@ -272,16 +272,16 @@ The configuration looks like: ```yaml connection: - methods: - - identifier: - type: guacamole - name: Classic - description: '' - ports: - metrics: 9118 - rdp: 3389 - environment: - ENVIRONMENT_VARIABLE: test + methods: + - identifier: + type: guacamole + name: Classic + description: '' + ports: + metrics: 9118 + rdp: 3389 + environment: + ENVIRONMENT_VARIABLE: test ``` #### HTTP(S) @@ -291,19 +291,19 @@ configuration looks like: ```yaml connection: - methods: - - identifier: - type: http - name: HTTP - description: '' - ports: - metrics: 9118 - http: 10000 - environment: - ENVIRONMENT_VARIABLE: test - redirect_url: '{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}' - cookies: - token: '{CAPELLACOLLAB_SESSION_TOKEN}' + methods: + - identifier: + type: http + name: HTTP + description: '' + ports: + metrics: 9118 + http: 10000 + environment: + ENVIRONMENT_VARIABLE: test + redirect_url: '{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}' + cookies: + token: '{CAPELLACOLLAB_SESSION_TOKEN}' ``` ##### Authentication diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 4dfee3deb..db4b0286a 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -33,12 +33,12 @@ to automate tasks such as creating and managing projects, sessions, and users. Please use these links to access the API documentation: -- [:octicons-link-external-16: SwaggerUI](swagger.md) (Interactive SwaggerUI - documentation) -- [:octicons-link-external-16: ReDoc](redoc.md) (Interactive ReDoc - documentation) -- [:octicons-link-external-16: OpenAPI Specification, formerly Swagger Specification](openapi.md) - (JSON) +- [:octicons-link-external-16: SwaggerUI](swagger.md) (Interactive SwaggerUI + documentation) +- [:octicons-link-external-16: ReDoc](redoc.md) (Interactive ReDoc + documentation) +- [:octicons-link-external-16: OpenAPI Specification, formerly Swagger Specification](openapi.md) + (JSON) ## Authentication diff --git a/docs/docs/development/backend/code-style.md b/docs/docs/development/backend/code-style.md index a71547a81..920416cec 100644 --- a/docs/docs/development/backend/code-style.md +++ b/docs/docs/development/backend/code-style.md @@ -8,62 +8,65 @@ We base our code style on a modified version of the [Google style guide] for Python code. The key differences are: -- **Docstrings**: The [Numpy style guide] applies here. - - When writing docstrings for functions, use the imperative style, as - per [PEP-257]. For example, write "Do X and Y" instead of "Does X and Y". - -- **Overridden methods**: If the documentation did not change from the base - class (i.e. the base class' method's docstring still applies without - modification), do not add a short docstring á la "See base class". This lets - automated tools pick up the full base class docstring instead, and is - therefore more useful in IDEs etc. - -- **Linting**: Use [pylint] for static code analysis, and [mypy] for static - type checking. - -- **Formatting**: Use [black] as code auto-formatter. The maximum line length - is 79, as per [PEP-8]. This setting should be automatically picked up from - the `pyproject.toml` file. The reason for the shorter line length is that it - avoids wrapping and overflows in side-by-side split views (e.g. diffs) if - there's also information displayed to the side of it (e.g. a tree view of the - modified files). - - Be aware of the different line length of 72 for docstrings. We - currently do not have a satisfactory solution to automatically apply - or enforce this. - - Note that, while you're encouraged to do so in general, it is not a hard - requirement to break up long strings into smaller parts. Additionally, never - break up strings that are presented to the user in e.g. log messages, as that - makes it significantly harder to grep for them. - - Use [isort] for automatic sorting of imports. Its settings should automatically - be picked up from the `pyproject.toml` file as well. - -- **Typing**: We do not make an exception for `typing` imports. Instead of - writing `from typing import SomeName`, use `import typing as t` and access - typing related classes like `t.TypedDict`. - - Use the new syntax and classes for typing introduced with Python 3.10. - - - Instead of `t.Tuple`, `t.List` etc. use the builtin classes `tuple`, `list` - etc. - - For classes that are not builtin (e.g. `Iterable`), `import collections.abc - as cabc` and then use them like `cabc.Iterable`. - - Use [PEP-604]-style unions, e.g. `int | float` instead of `t.Union[int, float]`. - - Use `... | None` (with `None` always as the last union member) instead of - `t.Optional[...]` and always explicitly annotate where `None` is possible. - -- **Python style rules**: For conflicting parts, the [black] code style wins. - If you have set up `black` correctly, you don't need to worry about this - though :) -- When working with `dict`s, consider using `t.TypedDict` instead of a more - generic `dict[str, float|int|str]`-like annotation where possible, as the - latter is much less precise (often requiring additional `assert`s or - `isinstance` checks to pass) and can grow unwieldy very quickly. -- Prefer `t.NamedTuple` over `collections.namedtuple`, because the former uses - a more convenient `class ...:` syntax and also supports type annotations. +- **Docstrings**: The [Numpy style guide] applies here. + + When writing docstrings for functions, use the imperative style, as per + [PEP-257]. For example, write "Do X and Y" instead of "Does X and Y". + +- **Overridden methods**: If the documentation did not change from the base + class (i.e. the base class' method's docstring still applies without + modification), do not add a short docstring á la "See base class". This + lets automated tools pick up the full base class docstring instead, and is + therefore more useful in IDEs etc. + +- **Linting**: Use [pylint] for static code analysis, and [mypy] for static + type checking. + +- **Formatting**: Use [black] as code auto-formatter. The maximum line length + is 79, as per [PEP-8]. This setting should be automatically picked up from + the `pyproject.toml` file. The reason for the shorter line length is that + it avoids wrapping and overflows in side-by-side split views (e.g. diffs) + if there's also information displayed to the side of it (e.g. a tree view + of the modified files). + + Be aware of the different line length of 72 for docstrings. We currently do + not have a satisfactory solution to automatically apply or enforce this. + + Note that, while you're encouraged to do so in general, it is not a hard + requirement to break up long strings into smaller parts. Additionally, + never break up strings that are presented to the user in e.g. log messages, + as that makes it significantly harder to grep for them. + + Use [isort] for automatic sorting of imports. Its settings should + automatically be picked up from the `pyproject.toml` file as well. + +- **Typing**: We do not make an exception for `typing` imports. Instead of + writing `from typing import SomeName`, use `import typing as t` and access + typing related classes like `t.TypedDict`. + + Use the new syntax and classes for typing introduced with Python 3.10. + + - Instead of `t.Tuple`, `t.List` etc. use the builtin classes `tuple`, + `list` etc. + - For classes that are not builtin (e.g. `Iterable`), + `import collections.abc as cabc` and then use them like + `cabc.Iterable`. + - Use [PEP-604]-style unions, e.g. `int | float` instead of + `t.Union[int, float]`. + - Use `... | None` (with `None` always as the last union member) instead + of `t.Optional[...]` and always explicitly annotate where `None` is + possible. + +- **Python style rules**: For conflicting parts, the [black] code style wins. + If you have set up `black` correctly, you don't need to worry about this + though :) +- When working with `dict`s, consider using `t.TypedDict` instead of a more + generic `dict[str, float|int|str]`-like annotation where possible, as the + latter is much less precise (often requiring additional `assert`s or + `isinstance` checks to pass) and can grow unwieldy very quickly. +- Prefer `t.NamedTuple` over `collections.namedtuple`, because the former + uses a more convenient `class ...:` syntax and also supports type + annotations. ## Conventions @@ -87,13 +90,13 @@ Python code. The key differences are: must add an `as xy` suffix to avoid naming conflicts with the first case. We follow this pattern: - `from capellacollab.extensions. import submodule as _` + `from capellacollab.extensions. import submodule as _` - For example, if we are in `capellacollab.sessions` and want to import - `crud` from `capellacollab.projects.toolsmodels`, we would do it like - this: + For example, if we are in `capellacollab.sessions` and want to import + `crud` from `capellacollab.projects.toolsmodels`, we would do it like + this: - `from capellacollab.projects.toolmodels import crud as toolmodels_crud` + `from capellacollab.projects.toolmodels import crud as toolmodels_crud` 1. Only use relative imports up to one level above the current one. This means you should use `from . import y` for the current module and @@ -102,8 +105,8 @@ Python code. The key differences are: ### Naming Conventions -- All SQLAlchemy models should have `Database` as a prefix, e.g., - `DatabaseProject` or `DatabaseUser`. +- All SQLAlchemy models should have `Database` as a prefix, e.g., + `DatabaseProject` or `DatabaseUser`. [google style guide]: https://google.github.io/styleguide/pyguide.html [numpy style guide]: https://numpydoc.readthedocs.io/en/latest/format.html @@ -114,4 +117,4 @@ Python code. The key differences are: [pylint]: https://github.com/PyCQA/pylint [isort]: https://github.com/PyCQA/isort [black]: - https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html + https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html diff --git a/docs/docs/development/docs.md b/docs/docs/development/docs.md index b43d7de27..c85cd53ac 100644 --- a/docs/docs/development/docs.md +++ b/docs/docs/development/docs.md @@ -46,9 +46,9 @@ old direction from breaking. This can be done by adding a line to the ```yaml plugins: - - redirects: - redirect_maps: - 'path/to/old/template.md': 'path/to/new/template.md' # Reason for the move + - redirects: + redirect_maps: + 'path/to/old/template.md': 'path/to/new/template.md' # Reason for the move ``` ### Tree structure diff --git a/docs/docs/development/frontend/customize.md b/docs/docs/development/frontend/customize.md index f3153991d..c5628b673 100644 --- a/docs/docs/development/frontend/customize.md +++ b/docs/docs/development/frontend/customize.md @@ -7,4 +7,4 @@ You can customize the frontend by using a custom theme and a custom favicon: -- If you like to use your custom favicon, please copy it to `src/favicon.ico` +- If you like to use your custom favicon, please copy it to `src/favicon.ico` diff --git a/docs/docs/development/frontend/responsive-design/mobile-view.md b/docs/docs/development/frontend/responsive-design/mobile-view.md index b696a659d..08630db7a 100644 --- a/docs/docs/development/frontend/responsive-design/mobile-view.md +++ b/docs/docs/development/frontend/responsive-design/mobile-view.md @@ -13,14 +13,14 @@ Our goal is to ensure all features are optimized for mobile view. ## Requirements -- Smallest width is 375px (iPhone SE) -- Smallest height is 667px (iPhone SE) -- The breakpoint width between mobile and desktop view is 1280px for the - navigation bar. When the screen is smaller than 1280px, the navigation bar is - hidden and can be expanded by clicking on the hamburger menu. The application - should be able to be used on all screen sizes that are wider than the - smallest width. Therefore the breakpoint can vary from component to - component. +- Smallest width is 375px (iPhone SE) +- Smallest height is 667px (iPhone SE) +- The breakpoint width between mobile and desktop view is 1280px for the + navigation bar. When the screen is smaller than 1280px, the navigation bar + is hidden and can be expanded by clicking on the hamburger menu. The + application should be able to be used on all screen sizes that are wider + than the smallest width. Therefore the breakpoint can vary from component + to component. ## Responsive design with TailwindCSS @@ -33,16 +33,16 @@ uses flexbox on devices larger than `768px`. ### Best Practices -- **Avoid Tables**: They're not natively responsive. Making them so demands - significant effort. -- **Leverage Flexboxes**: Ideally, utilize `class="flex flex-wrap"` to ensure - content adjusts appropriately on various screens. -- **Set Boundaries**: Implement `max-w-[90vw]` to avoid content spilling out of - view. You can change the `class="90vw"` to another value, depending on your - needs. -- **Centering Content**: When aesthetics and usability align, consider - vertically centering elements via `class="flex justify-center"` on the parent - element. +- **Avoid Tables**: They're not natively responsive. Making them so demands + significant effort. +- **Leverage Flexboxes**: Ideally, utilize `class="flex flex-wrap"` to ensure + content adjusts appropriately on various screens. +- **Set Boundaries**: Implement `max-w-[90vw]` to avoid content spilling out + of view. You can change the `class="90vw"` to another value, depending on + your needs. +- **Centering Content**: When aesthetics and usability align, consider + vertically centering elements via `class="flex justify-center"` on the + parent element. ### Example from the application diff --git a/docs/docs/development/frontend/routes.md b/docs/docs/development/frontend/routes.md index 55564c2ba..c1f1f0a57 100644 --- a/docs/docs/development/frontend/routes.md +++ b/docs/docs/development/frontend/routes.md @@ -9,32 +9,32 @@ 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. -- `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. +- `/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. +- `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. ## Examples Valid routes are: -- `/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. +- `/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`) +- `/project/create` (`project` should be plural) +- `/models` (`models` is a child resource of `projects`, therefore it should + be `/projects/:id/models`) diff --git a/docs/docs/development/frontend/storybook.md b/docs/docs/development/frontend/storybook.md index 84185b043..b2918f7bd 100644 --- a/docs/docs/development/frontend/storybook.md +++ b/docs/docs/development/frontend/storybook.md @@ -73,8 +73,8 @@ In the same directory of the component, add a file `{component_name}.docs.mdx` and use the following code as a template: ```mdx -import * as Component from './component-name.stories.ts' -import { Meta, Title, Story, Canvas, Unstyled } from '@storybook/blocks' +import * as Component from './component-name.stories.ts'; +import { Meta, Title, Story, Canvas, Unstyled } from '@storybook/blocks'; @@ -91,9 +91,9 @@ devices: ```mdx -
- -
+
+ +
``` diff --git a/docs/docs/development/frontend/testing.md b/docs/docs/development/frontend/testing.md index 03ae04c81..cb17c83d9 100644 --- a/docs/docs/development/frontend/testing.md +++ b/docs/docs/development/frontend/testing.md @@ -16,14 +16,14 @@ it against the potential benefits. ### Technologies -- We use [Jasmine] as testing framework -- [Karma] is used as test runner -- We use [istanbul] to measure and visualize the code coverage +- We use [Jasmine] as testing framework +- [Karma] is used as test runner +- We use [istanbul] to measure and visualize the code coverage ### Additional Sources -- [Official angular testing guide] -- Recommended: [Detailed angular testing guide] +- [Official angular testing guide] +- Recommended: [Detailed angular testing guide] ### General @@ -72,7 +72,7 @@ and what is missing, one can open the `index.html` file in the ### Technologies -- We use [playwright] for E2E testing +- We use [playwright] for E2E testing ### Test Generation diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md index c05ccf85f..f107f1be4 100644 --- a/docs/docs/development/index.md +++ b/docs/docs/development/index.md @@ -35,12 +35,12 @@ The k3d cluster is required for the development environment. ### Requirements -- [`Python`](https://www.python.org/) >= 3.12 -- [`Docker`](https://www.docker.com/) -- [`GNU Make`](https://www.gnu.org/software/make/) -- [`Node.js`](https://nodejs.org/en) >= v20.8.0 -- [`npm`](https://www.npmjs.com/) package manager -- [`Angular CLI`](https://angular.io/cli#installing-angular-cli) +- [`Python`](https://www.python.org/) >= 3.12 +- [`Docker`](https://www.docker.com/) +- [`GNU Make`](https://www.gnu.org/software/make/) +- [`Node.js`](https://nodejs.org/en) >= v20.8.0 +- [`npm`](https://www.npmjs.com/) package manager +- [`Angular CLI`](https://angular.io/cli#installing-angular-cli) ### Backend Configuration @@ -71,11 +71,11 @@ make dev If everything went well, the frontend and backend should be running now: -- [Frontend](http://localhost:4200) -- [Backend healthcheck](http://localhost:8000/healthcheck) -- [Backend API documentation](http://localhost:8000/docs) -- [Documentation](http://localhost:8081) -- [Storybook](http://localhost:6006) +- [Frontend](http://localhost:4200) +- [Backend healthcheck](http://localhost:8000/healthcheck) +- [Backend API documentation](http://localhost:8000/docs) +- [Documentation](http://localhost:8081) +- [Storybook](http://localhost:6006) ## General Notes diff --git a/docs/docs/development/pull_requests.md b/docs/docs/development/pull_requests.md index ce14cc4a1..271f4b23f 100644 --- a/docs/docs/development/pull_requests.md +++ b/docs/docs/development/pull_requests.md @@ -9,32 +9,33 @@ To reduce the burden on our maintainers, all PRs must meet the following criteria before we start the review process. If the acceptance criteria are not met, please mark the PR as a draft. -- All Github Action pipelines have to be green. If in individual cases the - pipeline cannot be fixed independently or the pipeline failure is unrelated - to the PR, then this should be justified in a comment in the pull request. -- The adapted code was sensibly covered with tests. Codecov will indicate the - test coverage with a comment. -- New features must be documented in the user documentation. If changes are - made to existing functionality, the existing documentation must be adapted. -- Frontend changes must always be mobile optimized / responsive. You can find - the requirements [here](./frontend/responsive-design/mobile-view.md). -- Migration scripts must also be written for changes to database models. They - can be auto-generated, more information can be found - [here](./backend/database-migration.md). -- The PR and commit descriptions describe the changes in a comprehensible way. - Breaking changes must be marked as such. Commit messages have to follow the - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) - specification. -- If there are conflicts with the main branch, they must be resolved. -- The frontend code must follow our - [frontend code style guide](./frontend/code-style.md). -- The backend code must follow our - [backend code style guide](./backend/code-style.md). -- Make sure that all raised exceptions use our - [custom exception classes](./backend/exception.md), which can be resolved by - the frontend. -- For each changed or added component in the frontend, a storybook story must - be created. You can find more information [here](./frontend/storybook.md). +- All Github Action pipelines have to be green. If in individual cases the + pipeline cannot be fixed independently or the pipeline failure is unrelated + to the PR, then this should be justified in a comment in the pull request. +- The adapted code was sensibly covered with tests. Codecov will indicate the + test coverage with a comment. +- New features must be documented in the user documentation. If changes are + made to existing functionality, the existing documentation must be adapted. +- Frontend changes must always be mobile optimized / responsive. You can find + the requirements [here](./frontend/responsive-design/mobile-view.md). +- Migration scripts must also be written for changes to database models. They + can be auto-generated, more information can be found + [here](./backend/database-migration.md). +- The PR and commit descriptions describe the changes in a comprehensible + way. Breaking changes must be marked as such. Commit messages have to + follow the + [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) + specification. +- If there are conflicts with the main branch, they must be resolved. +- The frontend code must follow our + [frontend code style guide](./frontend/code-style.md). +- The backend code must follow our + [backend code style guide](./backend/code-style.md). +- Make sure that all raised exceptions use our + [custom exception classes](./backend/exception.md), which can be resolved + by the frontend. +- For each changed or added component in the frontend, a storybook story must + be created. You can find more information [here](./frontend/storybook.md). Once all acceptance criteria are met, you can mark the PR as ready for review and a maintainer will review it. diff --git a/docs/docs/development/troubleshooting.md b/docs/docs/development/troubleshooting.md index c638a592e..845281ff9 100644 --- a/docs/docs/development/troubleshooting.md +++ b/docs/docs/development/troubleshooting.md @@ -12,17 +12,17 @@ fails with errors like "Could not resolve host", `k3d-myregistry.localhost` isn't resolved properly to `127.0.0.1`. To resolve this, you can try the following options: - -- On Debian/Ubuntu based systems, you can install nss-myhostname. - `nss-myhostname` resolves all subdomains of localhost to localhost: - ```sh - sudo apt install libnss-myhostname - ``` +- On Debian/Ubuntu based systems, you can install nss-myhostname. + `nss-myhostname` resolves all subdomains of localhost to localhost: -- Add the following line to the `/etc/hosts` on the host machine: - ``` - 127.0.0.1 k3d-myregistry.localhost - ``` + ```sh + sudo apt install libnss-myhostname + ``` + +- Add the following line to the `/etc/hosts` on the host machine: + ``` + 127.0.0.1 k3d-myregistry.localhost + ``` After applying the steps, verify that the registry is reachable by running `make reach-registry` again. diff --git a/docs/docs/index.md b/docs/docs/index.md index 082a669df..329a3abc6 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -7,11 +7,11 @@ Welcome to the official documentation of the Capella Collaboration Manager. To continue, please select one of the following options: -- I am a user of the platform or interested in its features: - [User documentation](./user/index.md) -- I am a user of the platform interested in automating my tasks or integrating - with other systems: [API Documentation](./api/index.md) -- I am a system administrator and want to learn how to install and configure - the platform: [Administrator documentation](./admin/index.md) -- I am a developer and want to learn how to extend the platform: - [Developer documentation](./development/index.md) +- I am a user of the platform or interested in its features: + [User documentation](./user/index.md) +- I am a user of the platform interested in automating my tasks or + integrating with other systems: [API Documentation](./api/index.md) +- I am a system administrator and want to learn how to install and configure + the platform: [Administrator documentation](./admin/index.md) +- I am a developer and want to learn how to extend the platform: + [Developer documentation](./development/index.md) diff --git a/docs/docs/release-notes.md b/docs/docs/release-notes.md index b1fbaca03..704e15961 100644 --- a/docs/docs/release-notes.md +++ b/docs/docs/release-notes.md @@ -3,19 +3,22 @@ ~ SPDX-License-Identifier: Apache-2.0 --> - -- Release notes of the **Capella Collaboration Manager** are available [here](https://github.com/DSD-DBS/capella-collab-manager/releases). -- **Session related** release notes are available [here](https://github.com/DSD-DBS/capella-dockerimages/releases). +- Release notes of the **Capella Collaboration Manager** are available + [here](https://github.com/DSD-DBS/capella-collab-manager/releases). +- **Session related** release notes are available + [here](https://github.com/DSD-DBS/capella-dockerimages/releases). - - **JupyterLab** release notes are available - [here](https://jupyterlab.readthedocs.io/en/stable/getting_started/changelog.html). - - **capellambse** release notes are available [here](https://github.com/DSD-DBS/py-capellambse/releases).
- **capellambse context diagrams** release notes are available [here](https://github.com/DSD-DBS/capellambse-context-diagrams/releases). - - **Capella** release notes are available - [here](https://github.com/eclipse/capella/releases).
- **TeamForCapella** release notes are available - [here](https://www.obeosoft.com/en/team-for-capella-releases). - - **Papyrus** release notes are avilable - [here](https://eclipse.dev/papyrus/news.php). - - **pure::variants** release notes are available - [here](https://www.pure-systems.com/pv-update/additions/doc/ChangeLog.txt). + - **JupyterLab** release notes are available + [here](https://jupyterlab.readthedocs.io/en/stable/getting_started/changelog.html). + - **capellambse** release notes are available + [here](https://github.com/DSD-DBS/py-capellambse/releases).
+ **capellambse context diagrams** release notes are available + [here](https://github.com/DSD-DBS/capellambse-context-diagrams/releases). + - **Capella** release notes are available + [here](https://github.com/eclipse/capella/releases).
+ **TeamForCapella** release notes are available + [here](https://www.obeosoft.com/en/team-for-capella-releases). + - **Papyrus** release notes are avilable + [here](https://eclipse.dev/papyrus/news.php). + - **pure::variants** release notes are available + [here](https://www.pure-systems.com/pv-update/additions/doc/ChangeLog.txt). diff --git a/docs/docs/user/index.md b/docs/docs/user/index.md index 552a9cc6d..0be03e801 100644 --- a/docs/docs/user/index.md +++ b/docs/docs/user/index.md @@ -24,20 +24,20 @@ since the site is completely responsive it is also usable on smartphones. Git is quite in the middle of the modeling lifecycle. We also use its automation means (CI/CD) to automate a number of housekeeping activities: -- Automated model-modifications: This includes range of services like - human-friendly element ID assignment, change control and versioning of - elements, hyperlinked object title update in descriptions and maintenance of - model-derived requirements (req-bot). -- Derived product generation and distribution: generation and publication of - model-derived documents and other artifacts (like software interfaces, - configurations); caching of diagrams for faster display in linked pages and - web-viewer; computation of model metrics for modeling progress dashboards; - spell-checking; synchronization with tools like - [Simulink](https://mathworks.com/products/simulink.html), - [Polarion](https://polarion.plm.automation.siemens.com/), - [Codebeamer](https://codebeamer.com/), - [Confluence](https://www.atlassian.com/software/confluence) or even - [Grafana](https://grafana.com/). +- Automated model-modifications: This includes range of services like + human-friendly element ID assignment, change control and versioning of + elements, hyperlinked object title update in descriptions and maintenance + of model-derived requirements (req-bot). +- Derived product generation and distribution: generation and publication of + model-derived documents and other artifacts (like software interfaces, + configurations); caching of diagrams for faster display in linked pages and + web-viewer; computation of model metrics for modeling progress dashboards; + spell-checking; synchronization with tools like + [Simulink](https://mathworks.com/products/simulink.html), + [Polarion](https://polarion.plm.automation.siemens.com/), + [Codebeamer](https://codebeamer.com/), + [Confluence](https://www.atlassian.com/software/confluence) or even + [Grafana](https://grafana.com/). At this moment Collaboration Manager doesn't provide you with a self-service to configure any of these automations, however since now you know these are @@ -64,16 +64,16 @@ one could run it in a VM). There are currently 2 session types supported: -- **Read-only session** - in this case Collaboration Manager gets the latest - (or user-selected) model version from git and places that into a read-only - workspace within Capella. You can "play" with that model and even make - changes, however these changes will not be saved and so will do no harm (for - instance to agreed / approved contents). When the session is closed the - contents of the workspace is gone. -- **Persistent workspace** - in this mode a user-specific persistent volume is - mounted to the Session pod and linked to Capella as the workspace. This - enables you to work on projects locally, via git or TeamForCapella as - persistent workspace keeps "state" even after the session is closed. +- **Read-only session** - in this case Collaboration Manager gets the latest + (or user-selected) model version from git and places that into a read-only + workspace within Capella. You can "play" with that model and even make + changes, however these changes will not be saved and so will do no harm + (for instance to agreed / approved contents). When the session is closed + the contents of the workspace is gone. +- **Persistent workspace** - in this mode a user-specific persistent volume + is mounted to the Session pod and linked to Capella as the workspace. This + enables you to work on projects locally, via git or TeamForCapella as + persistent workspace keeps "state" even after the session is closed. We do currently support two different working modes: `TeamForCapella` and `Git`. If you want to get more information about it, we have prepared a @@ -84,18 +84,18 @@ comparison here: There are 3 roles you can have in a project context: -- **User - read-only** - you can view model snapshots (latest model, any - specific release, branch or commit) from git. You may edit the model however - your changes will not be saved. (Makes it also useful for training - exercises.) -- **User - read/write** - you start a **Persistent Workspace Session**. Your - user account is allowed to clone and commit to a git project — if the project - co-working model is git-only — or allowed to connect to a remote repository - in a TeamForCapella-based project. Also in this mode you may have many - co-working projects open at the same time, given that you have a role in - those projects that allows this kind of access. -- **Model manager** - can do same as both users above but also can invite or - remove users from the managed projects and control their access rights. +- **User - read-only** - you can view model snapshots (latest model, any + specific release, branch or commit) from git. You may edit the model + however your changes will not be saved. (Makes it also useful for training + exercises.) +- **User - read/write** - you start a **Persistent Workspace Session**. Your + user account is allowed to clone and commit to a git project — if the + project co-working model is git-only — or allowed to connect to a remote + repository in a TeamForCapella-based project. Also in this mode you may + have many co-working projects open at the same time, given that you have a + role in those projects that allows this kind of access. +- **Model manager** - can do same as both users above but also can invite or + remove users from the managed projects and control their access rights. You may also [learn more about the roles model here](projects/roles.md). @@ -114,10 +114,10 @@ it yet or can't find the project you need see At this point you may want to continue to one of the detailed getting-started sections: -- [General introduction to Capella and first steps](tools/capella/introduction.md) -- [Getting started with a Read-only Session](sessions/types/read-only.md) -- [Getting started with a TeamForCapella-based Project](sessions/types/persistent.md) -- [Getting started with a Git-based Project](tools/capella/git/index.md) +- [General introduction to Capella and first steps](tools/capella/introduction.md) +- [Getting started with a Read-only Session](sessions/types/read-only.md) +- [Getting started with a TeamForCapella-based Project](sessions/types/persistent.md) +- [Getting started with a Git-based Project](tools/capella/git/index.md) ## Missing Information / Need Support diff --git a/docs/docs/user/projects/add-user/index.md b/docs/docs/user/projects/add-user/index.md index 4b5c5f4bc..59ee75d57 100644 --- a/docs/docs/user/projects/add-user/index.md +++ b/docs/docs/user/projects/add-user/index.md @@ -24,7 +24,7 @@ 1. `Role` and `Permission`: Have a look here for the overview of Roles and Permissions: [Project roles](../../projects/roles.md) - ![Add user](./add-user.png) + ![Add user](./add-user.png) ## Modify Role or Permissions of User @@ -36,11 +36,12 @@ You can select from the following options: - - Remove a user from the project - - Set role of the user to [project lead](../../projects/roles.md) or - [user](../../projects/roles.md) - - Set permission of the user to [read/write](../../sessions/types/index.md) - or [read-only](../../sessions/types/index.md) + - Remove a user from the project + - Set role of the user to [project lead](../../projects/roles.md) or + [user](../../projects/roles.md) + - Set permission of the user to + [read/write](../../sessions/types/index.md) or + [read-only](../../sessions/types/index.md) !!! info diff --git a/docs/docs/user/projects/models/complexity_badge.md b/docs/docs/user/projects/models/complexity_badge.md index 36740eba0..601508950 100644 --- a/docs/docs/user/projects/models/complexity_badge.md +++ b/docs/docs/user/projects/models/complexity_badge.md @@ -32,8 +32,8 @@ 1. Follow the CI template instructions - - [Gitlab](https://github.com/DSD-DBS/py-capellambse/tree/master/ci-templates/gitlab#model-badge) - - [Github](https://github.com/DSD-DBS/py-capellambse/tree/master/ci-templates/github#model-badge) + - [Gitlab](https://github.com/DSD-DBS/py-capellambse/tree/master/ci-templates/gitlab#model-badge) + - [Github](https://github.com/DSD-DBS/py-capellambse/tree/master/ci-templates/github#model-badge) to add the complexity badge pipeline to the linked repository. diff --git a/docs/docs/user/projects/models/create.md b/docs/docs/user/projects/models/create.md index 82078f22f..c34031b62 100644 --- a/docs/docs/user/projects/models/create.md +++ b/docs/docs/user/projects/models/create.md @@ -69,10 +69,10 @@ You have to enter the following information: here, which is needed to access the repository. Please note that we don't have support for SSH authentication yet. - - For public repositories: You don't need to enter credentials. However, - backups will need credentials to be able to push to the repository. - - For private repositories: You need to enter credentials for read-only - sessions and backups. + - For public repositories: You don't need to enter credentials. However, + backups will need credentials to be able to push to the repository. + - For private repositories: You need to enter credentials for read-only + sessions and backups. !!! danger diff --git a/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md b/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md index b73cf668b..6fc5fb7d4 100644 --- a/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md +++ b/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md @@ -37,8 +37,8 @@ 1. Follow the CI template instructions - - [Gitlab](https://dsd-dbs.github.io/capella-dockerimages/ci-templates/gitlab/diagram-cache/) - - [Github](https://dsd-dbs.github.io/capella-dockerimages/ci-templates/github/diagram-cache/) + - [Gitlab](https://dsd-dbs.github.io/capella-dockerimages/ci-templates/gitlab/diagram-cache/) + - [Github](https://dsd-dbs.github.io/capella-dockerimages/ci-templates/github/diagram-cache/) to add the diagram cache pipeline to the linked repository. diff --git a/docs/docs/user/sessions/jupyter/collaboration.md b/docs/docs/user/sessions/jupyter/collaboration.md index 595d517cc..29d4da65f 100644 --- a/docs/docs/user/sessions/jupyter/collaboration.md +++ b/docs/docs/user/sessions/jupyter/collaboration.md @@ -12,8 +12,8 @@ create a shared space accessible by all project members. ### Permissions -- **Read/Write Permission**: Allows users to edit the notebook files. -- **Read-only Permission**: Grants view-only access to the Jupyter notebooks. +- **Read/Write Permission**: Allows users to edit the notebook files. +- **Read-only Permission**: Grants view-only access to the Jupyter notebooks. ### Create Project Notebook Share diff --git a/docs/docs/user/tools/capella/t4c-git-compare.md b/docs/docs/user/tools/capella/t4c-git-compare.md index 440563e1b..b43aee6b9 100644 --- a/docs/docs/user/tools/capella/t4c-git-compare.md +++ b/docs/docs/user/tools/capella/t4c-git-compare.md @@ -86,27 +86,28 @@ ## Some General Words - -- **Git-only** - the modeling team uses a git repository to work on the model. - The team may use git branches to work on features or capabilities in parallel - and a main branch is used for integration and release-tagging. This way of - working gives the modeling leads / change control board great control over - what contents make it to the model that is used for releases (of things like - design documentation). On the downside this co-working method is fairly - complicated and requires skilled modeling leadership for challenges like - merge conflict resolution and fragmentation management (a way to break up - model into smaller files to reduce density of merge conflicts). -- **Git + TeamForCapella** - with this approach the modeling team can co-work - with a very high degree of concurrency and stay away from the difficulties of - merge conflict resolution. On the downside it is much harder to control what - makes it into the model as there is no barrier except for maybe a modeling - process that would stop a person from making changes that are not allowed. - Yet there are a few ways around that limitation. For teams with basic or no - experience in modeling and git this is probably the best way to start - co-woking. Git is still used for nightly backup of the model and - release-tagging. +- **Git-only** - the modeling team uses a git repository to work on the + model. The team may use git branches to work on features or capabilities in + parallel and a main branch is used for integration and release-tagging. + This way of working gives the modeling leads / change control board great + control over what contents make it to the model that is used for releases + (of things like design documentation). On the downside this co-working + method is fairly complicated and requires skilled modeling leadership for + challenges like merge conflict resolution and fragmentation management (a + way to break up model into smaller files to reduce density of merge + conflicts). +- **Git + TeamForCapella** - with this approach the modeling team can co-work + with a very high degree of concurrency and stay away from the difficulties + of merge conflict resolution. On the downside it is much harder to control + what makes it into the model as there is no barrier except for maybe a + modeling process that would stop a person from making changes that are not + allowed. Yet there are a few ways around that limitation. For teams with + basic or no experience in modeling and git this is probably the best way to + start co-woking. Git is still used for nightly backup of the model and + release-tagging. + + !!! info "TeamForCapella license required" - !!! info "Info: TeamForCapella license required" For this co-working method to be enabled you need a valid TeamForCapella license and TeamForCapella server installed and integrated with Collab-Manager.