diff --git a/backend/capellacollab/__main__.py b/backend/capellacollab/__main__.py index 224fe7caf0..b254fe014b 100644 --- a/backend/capellacollab/__main__.py +++ b/backend/capellacollab/__main__.py @@ -45,6 +45,8 @@ from capellacollab.tools import exceptions as tools_exceptions from capellacollab.users import exceptions as users_exceptions +from . import __version__ + handlers: list[logging.Handler] = [ logging.StreamHandler(), core_logging.CustomTimedRotatingFileHandler( @@ -78,6 +80,7 @@ async def shutdown(): app = fastapi.FastAPI( title="Capella Collaboration", + version=__version__, on_startup=[ startup, idletimeout.terminate_idle_sessions_in_background, @@ -99,8 +102,20 @@ async def shutdown(): middleware.Middleware(starlette_prometheus.PrometheusMiddleware), ], on_shutdown=[shutdown], + openapi_url="/api/docs/openapi.json", + docs_url="/api/docs/openapi", + redoc_url="/api/docs/redoc", ) + +@app.get( + "/docs", response_class=responses.RedirectResponse, include_in_schema=False +) +def redirect_docs(): + """Redirect `/docs` to new OpenAPI documentation location.""" + return responses.RedirectResponse("/api/docs/openapi") + + fastapi_pagination.add_pagination(app) diff --git a/docs/docs/admin/alerts/create.md b/docs/docs/admin/alerts/create.md index 89ec68dcbe..ccf0b45390 100644 --- a/docs/docs/admin/alerts/create.md +++ b/docs/docs/admin/alerts/create.md @@ -3,16 +3,12 @@ ~ SPDX-License-Identifier: Apache-2.0 --> - -!!! Warning "Usage restricted" - You need to be administrator to use this feature. - Alerts can be used to inform users about changes, news or maintenance work. The alerts are displayed to each user. -1. Please navigate to `Profile` → `Settings` +1. Please navigate to `Menu` → `Settings` 2. Fill in all required fields in the `Create an alert` form. ![Create an alert](create.png) diff --git a/docs/docs/admin/settings/model-sources/git.md b/docs/docs/admin/settings/model-sources/git.md index 2e2ad41459..0af175f97f 100644 --- a/docs/docs/admin/settings/model-sources/git.md +++ b/docs/docs/admin/settings/model-sources/git.md @@ -16,7 +16,7 @@ Gitlab, are not available. ## Define a Git Instance -1. Please navigate to `Profile` > `Settings` +1. Please navigate to `Menu` > `Settings` 1. Select `Git` below `Model sources` 1. You can see all existing instances (if any). To add a new integration, please use the form below "Add new integration". You have to enter the diff --git a/docs/docs/admin/settings/monitoring.md b/docs/docs/admin/settings/monitoring.md index 1be7b6d900..0d9279deec 100644 --- a/docs/docs/admin/settings/monitoring.md +++ b/docs/docs/admin/settings/monitoring.md @@ -8,4 +8,4 @@ To get a general overview of the status of pipelines and model modifiers for all registered models, a monitoring dashboard is provided. -You can find it going to `Profile` > `Settings` > `Monitoring` +You can find it going to `Menu` > `Settings` > `Monitoring` diff --git a/docs/docs/admin/teamforcapella/full-setup/full-setup.md b/docs/docs/admin/teamforcapella/full-setup/full-setup.md new file mode 100644 index 0000000000..b8af00fb0f --- /dev/null +++ b/docs/docs/admin/teamforcapella/full-setup/full-setup.md @@ -0,0 +1,23 @@ + + +# Full Setup of a TeamForCapella Project + +This tutorial will guide you through the full setup of a new TeamForCapella +based project in the Collaboration Manager. + +1. First of all, create a new project: + [Create a new project](/user/projects/create.md) +1. Create new tool model +1. Make sure that version and nature is selected! +1. Add the TeamForCapella integration +1. Add the Git integration +1. Create empty Capella model +1. Export model to T4C server +1. Set up a pipeline +1. Set up a model complexity badge +1. Set up the diagram cache + +Have fun! diff --git a/docs/docs/user/tools/capella/teamforcapella/update.md b/docs/docs/admin/teamforcapella/migration/update.md similarity index 58% rename from docs/docs/user/tools/capella/teamforcapella/update.md rename to docs/docs/admin/teamforcapella/migration/update.md index 776e948d1b..0eb33e1b68 100644 --- a/docs/docs/user/tools/capella/teamforcapella/update.md +++ b/docs/docs/admin/teamforcapella/migration/update.md @@ -13,31 +13,31 @@ 1. Open a new persistent session with the old Capella version. 1. Import the model from the TeamForCapella server via the Import wizzard from TeamForCapella into your local workspace: - [Import a model from TeamForCapella](./import/import-from-t4c.md) + [Import a model from TeamForCapella](/user/tools/capella/teamforcapella/import/import-from-t4c.md) 1. Terminate the session. 1. Remove existing backups from TeamForCapella: - [Remove a (nightly) backup](../../../projects/models/backups/remove.md) + [Remove a (nightly) backup](/user/projects/models/backups/remove.md) 1. Add a new repository in the TeamForCapella settings: - [Add a new TeamForCapella repository](./repository-management.md#add-a-new-teamforcapella-repository) + [Add a new TeamForCapella repository](/admin/teamforcapella/repository-management/repository-management.md#add-a-new-teamforcapella-repository) 1. Unlink the old TeamForCapella repository (old Capella version) from your model: - [Unlink a TeamForCapella repository](../../../projects/models/sources/t4c.md#unlink-a-teamforcapella-repository-from-a-project-model) + [Unlink a TeamForCapella repository](/user/projects/models/sources/t4c.md#unlink-a-teamforcapella-repository-from-a-project-model) 1. Link the new TeamForCapella repository (new Capella version) to your model: - [Link a TeamForCapella repository](../../../projects/models/sources/t4c.md#link-a-teamforcapella-repository-to-a-project-model) + [Link a TeamForCapella repository](/user/projects/models/sources/t4c.md#link-a-teamforcapella-repository-to-a-project-model) 1. Update the model version to the newer Capella version: - [Change model metadata](../../../projects/models/metadata.md) + [Change model metadata](/user/projects/models/metadata.md) 1. Create a new session with the new Capella version. 1. In your persistent workspace, execute the following steps: 1. Right click on the model in your workspace. 1. Select `Migration` and `Migrate Project toward current version` - ![Migrate Capella model](./migrate-capella-model.png) + ![Migrate Capella model](/user/tools/capella/migration/migrate-capella-model.png) 1. A backup is not required as the latest version should still be available on the old TeamForCapella server. - ![Disable backup option](./backup-migration.png) + ![Disable backup option](/user/tools/capella/migration/backup-migration.png) 1. Export the model to the new TeamForCapella server via the Export wizzard from TeamForCapella: - [Export a model to TeamForCapella](./export/export-to-t4c.md) -1. Recreate the backup from TeamForCapella: - [Set up a TeamForCapella backup](../../../projects/models/backups/setup.md) + [Export a model to TeamForCapella](/user/tools/capella/export/export-to-t4c.md) +1. Recreate the backup pipeline: + [Set up a TeamForCapella backup](/user/projects/models/backups/setup.md) diff --git a/docs/docs/user/projects/models/sources/t4c.md b/docs/docs/admin/teamforcapella/project-integration/project-integration.md similarity index 84% rename from docs/docs/user/projects/models/sources/t4c.md rename to docs/docs/admin/teamforcapella/project-integration/project-integration.md index 56cc8429ae..cf3bf56ad0 100644 --- a/docs/docs/user/projects/models/sources/t4c.md +++ b/docs/docs/admin/teamforcapella/project-integration/project-integration.md @@ -5,13 +5,9 @@ # Manage the TeamForCapella Project Integration - -!!! warning - The TeamForCapella project integration can only be managed by administrators. - If you need help, contact your administrator. - For all actions, you need to navigate to `Projects`, and select the model -sources button for the model.
![Model sources](./open-modelsources.png) +sources button for the model.
+![Model sources](./screenshots/open-modelsources.png) ## Link a TeamForCapella Repository to a Project Model diff --git a/docs/docs/user/projects/models/sources/open-modelsources.png b/docs/docs/admin/teamforcapella/project-integration/screenshots/open-modelsources.png similarity index 100% rename from docs/docs/user/projects/models/sources/open-modelsources.png rename to docs/docs/admin/teamforcapella/project-integration/screenshots/open-modelsources.png diff --git a/docs/docs/user/projects/models/sources/open-modelsources.png.license b/docs/docs/admin/teamforcapella/project-integration/screenshots/open-modelsources.png.license similarity index 100% rename from docs/docs/user/projects/models/sources/open-modelsources.png.license rename to docs/docs/admin/teamforcapella/project-integration/screenshots/open-modelsources.png.license diff --git a/docs/docs/user/projects/models/sources/use-existing-repository.png b/docs/docs/admin/teamforcapella/project-integration/screenshots/use-existing-repository.png similarity index 100% rename from docs/docs/user/projects/models/sources/use-existing-repository.png rename to docs/docs/admin/teamforcapella/project-integration/screenshots/use-existing-repository.png diff --git a/docs/docs/user/projects/models/sources/use-existing-repository.png.license b/docs/docs/admin/teamforcapella/project-integration/screenshots/use-existing-repository.png.license similarity index 100% rename from docs/docs/user/projects/models/sources/use-existing-repository.png.license rename to docs/docs/admin/teamforcapella/project-integration/screenshots/use-existing-repository.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/activate-t4c-administration-guide.png b/docs/docs/admin/teamforcapella/project-management/activate-t4c-administration-guide.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/activate-t4c-administration-guide.png rename to docs/docs/admin/teamforcapella/project-management/activate-t4c-administration-guide.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/activate-t4c-administration-guide.png.license b/docs/docs/admin/teamforcapella/project-management/activate-t4c-administration-guide.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/activate-t4c-administration-guide.png.license rename to docs/docs/admin/teamforcapella/project-management/activate-t4c-administration-guide.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/add-new-cdo-session.png b/docs/docs/admin/teamforcapella/project-management/add-new-cdo-session.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/add-new-cdo-session.png rename to docs/docs/admin/teamforcapella/project-management/add-new-cdo-session.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/add-new-cdo-session.png.license b/docs/docs/admin/teamforcapella/project-management/add-new-cdo-session.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/add-new-cdo-session.png.license rename to docs/docs/admin/teamforcapella/project-management/add-new-cdo-session.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/delete-t4c-project.png b/docs/docs/admin/teamforcapella/project-management/delete-t4c-project.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/delete-t4c-project.png rename to docs/docs/admin/teamforcapella/project-management/delete-t4c-project.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/delete-t4c-project.png.license b/docs/docs/admin/teamforcapella/project-management/delete-t4c-project.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/delete-t4c-project.png.license rename to docs/docs/admin/teamforcapella/project-management/delete-t4c-project.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/find-out-repository-host.png b/docs/docs/admin/teamforcapella/project-management/find-out-repository-host.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/find-out-repository-host.png rename to docs/docs/admin/teamforcapella/project-management/find-out-repository-host.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/find-out-repository-host.png.license b/docs/docs/admin/teamforcapella/project-management/find-out-repository-host.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/find-out-repository-host.png.license rename to docs/docs/admin/teamforcapella/project-management/find-out-repository-host.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-session.png b/docs/docs/admin/teamforcapella/project-management/open-cdo-session.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-session.png rename to docs/docs/admin/teamforcapella/project-management/open-cdo-session.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-session.png.license b/docs/docs/admin/teamforcapella/project-management/open-cdo-session.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-session.png.license rename to docs/docs/admin/teamforcapella/project-management/open-cdo-session.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-transaction.png b/docs/docs/admin/teamforcapella/project-management/open-cdo-transaction.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-transaction.png rename to docs/docs/admin/teamforcapella/project-management/open-cdo-transaction.png diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-transaction.png.license b/docs/docs/admin/teamforcapella/project-management/open-cdo-transaction.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/project-management/open-cdo-transaction.png.license rename to docs/docs/admin/teamforcapella/project-management/open-cdo-transaction.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md b/docs/docs/admin/teamforcapella/project-management/project-management.md similarity index 85% rename from docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md rename to docs/docs/admin/teamforcapella/project-management/project-management.md index 37275030bf..b123a834d9 100644 --- a/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md +++ b/docs/docs/admin/teamforcapella/project-management/project-management.md @@ -8,22 +8,21 @@ This page describes how to manage T4C projects in T4C repositories. It does not cover the management of T4C repositories. For the management of T4C repositories, refer to the -[TeamForCapella repository management](../repository-management.md) guide. +[TeamForCapella repository management](../repository-management/repository-management.md) +guide. ## Create a new TeamForCapella Project 1. Make sure that you have a T4C repository available. If not, refer to the - [TeamForCapella repository management](../repository-management.md) guide. + [TeamForCapella repository management](../repository-management/repository-management.md) + guide. 1. Create an empty Capella project in your workspace. Then, export it to the T4C repository. For more information, refer to the - [TeamForCapella project export](../export/export-to-t4c.md) guide. + [TeamForCapella project export](/user/tools/capella/teamforcapella/export/export-to-t4c.md) + guide. ## Delete a TeamForCapella Project -!!! warning - - To delete a TeamForCapella project, you have to be global administrator in Collaboration Manager. - 1. Open a persistent Capella session and connect to it. 1. Enable the TeamForCapella administration capability:
`Window` > @@ -39,7 +38,7 @@ repositories, refer to the 1. Global administrators can navigate to `Profile` > `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](../../../../sessions/flows/t4c.md) + the [Connect to a TeamForCapella repository](/user/tools/capella/teamforcapella/connect/connect-to-t4c.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) diff --git a/docs/docs/user/tools/capella/teamforcapella/repository-management.md b/docs/docs/admin/teamforcapella/repository-management/repository-management.md similarity index 73% rename from docs/docs/user/tools/capella/teamforcapella/repository-management.md rename to docs/docs/admin/teamforcapella/repository-management/repository-management.md index 1faa493fd7..77def8cb75 100644 --- a/docs/docs/user/tools/capella/teamforcapella/repository-management.md +++ b/docs/docs/admin/teamforcapella/repository-management/repository-management.md @@ -5,14 +5,10 @@ # TeamForCapella Repository Management - -!!! info - TeamForCapella repositories can only be managed by administrators. - -For all actions, you have to navigate to `Profile` > `Settings` > -`TeamForCapella` (below `Model sources`). Select your instance. On the right -side, you should see a card with the name `Manage T4C repositories`. In this -card, you can see all existing repositories with their status. +For all actions, you have to navigate to `Menu` > `Settings` > `TeamForCapella` +(below `Model sources`). Select your instance. On the right side, you should +see a card with the name `Manage T4C repositories`. In this card, you can see +all existing repositories with their status. ## Add a new TeamForCapella Repository diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md new file mode 100644 index 0000000000..f6b37df802 --- /dev/null +++ b/docs/docs/api/index.md @@ -0,0 +1,117 @@ + + +# Automate tasks with our API + +Our API is designed to be simple and easy to use. It is based on RESTful +principles and uses standard HTTP methods. This means that you can use the API +to automate tasks such as creating and managing projects, sessions, and users. + + +!!! warning + We try to keep the API as stable as possible, but we cannot guarantee that + it will not change in the future. If you are using the API, make sure to + check our [release notes](https://github.com/DSD-DBS/capella-collab-manager/releases) + for any breaking changes. + +## API Documentation + +Please use these links to access the API documentation: + +- [:octicons-link-external-16: SwaggerUI](swaggerui.md) (Interactive OpenAPI + documentation) +- [:octicons-link-external-16: ReDoc](redoc.md) (Interactive ReDoc + documentation) +- [:octicons-link-external-16: OpenAPI Specification, formerly Swagger Specification](openapi.md) + (JSON) + + +!!! note + The API documentation is only available via the documentation + of Collaboration Manager instances. Only in this case you'll be able + to open the links above. You'll see the API documentation matching the + version of the Collaboration Manager instance you are using. + + It is not available on: + + - GitHub Pages + - Local non-cluster development environments + - ReadTheDocs + +## Authentication + +To authenticate against the API you can use Personal Access Tokens (PAT). + +### PAT Creation + +To create a personal access token (PAT) you can go to `Menu` > `Tokens`, insert +a short description and pick a date until when the token should be valid. + + +!!! info + The token which is generated will disappear after leaving the page. + Make sure you save it - you won't be able to access it again. + +### PAT Scope + +Personal access token have the same scope as the user who created it. It is +therefore important that you never pass on the token and treat it responsibly. +All requests are made in the name of the user who issued the token and are +logged accordingly. If you feel that the token has been lost, revoke it +immediately and inform the Systems Engineering Toolchain team. + +### Revoke a PAT + +In order to revoke a token go to `Menu` > `Token`. There you can see a list of +all tokens that belong to your user. By clicking on the delete button, you can +delete a token, which will no longer be valid for authentication. + +### PAT Usage + +You can use the token for basic authentication against the API. Use the token +as password and your username as username. + +#### Example with Python + +```py +import requests + +base_url = "example.com" # Replace with your base URL + +requests.get( + f"https://{base_url}/api/v1/projects", + auth=("username", "token") +) +``` + +#### Example with cURL + +With `cURL` you can use the following command to fetch the list of projects: + +```zsh +curl -u [username]:[token] https://[baseURL]/api/v1/projects +``` + +#### Example with `capellambse` + +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). + +```python +model = capellambse.model.MelodyModel( + path="", + diagram_cache={ + "path": "https:///api/v1/projects//models//diagrams/%s", + "username": "", + "password": "", + } +) +``` + +Having created a model like that you can e.g. with `model.diagrams[0]` get the +first diagram. diff --git a/docs/docs/api/openapi.md b/docs/docs/api/openapi.md new file mode 100644 index 0000000000..0336c9552f --- /dev/null +++ b/docs/docs/api/openapi.md @@ -0,0 +1,11 @@ +--- +template: redirect.html +location: /api/docs/openapi.json +title: OpenAPI Specification +icon: octicons/link-external-16 +--- + + diff --git a/docs/docs/user/sessions/flows/git.md b/docs/docs/api/redoc.md similarity index 53% rename from docs/docs/user/sessions/flows/git.md rename to docs/docs/api/redoc.md index dba3ac1c01..8ed90b7e09 100644 --- a/docs/docs/user/sessions/flows/git.md +++ b/docs/docs/api/redoc.md @@ -1,6 +1,11 @@ +--- +template: redirect.html +location: /api/docs/redoc +title: ReDoc +icon: octicons/link-external-16 +--- + - -The documentation for the Git workflow will follow in the future. diff --git a/docs/docs/api/swaggerui.md b/docs/docs/api/swaggerui.md new file mode 100644 index 0000000000..01ca5da96e --- /dev/null +++ b/docs/docs/api/swaggerui.md @@ -0,0 +1,11 @@ +--- +template: redirect.html +location: /api/docs/openapi +title: SwaggerUI +icon: octicons/link-external-16 +--- + + diff --git a/docs/docs/development/backend/authentication.md b/docs/docs/development/backend/authentication.md index c8d42e91e0..08be021cf8 100644 --- a/docs/docs/development/backend/authentication.md +++ b/docs/docs/development/backend/authentication.md @@ -3,15 +3,20 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -## Authentication via Personal Access Token (Requires a Running Frontend) +The are two common ways to authenticate against the backend in a development +environment. The first is to use a personal access token (PAT) and the second +is to use a bearer token. -Find more information about authentication with personal access tokens in the -user documentation: [Authentication](../../user/tokens.md) +## Personal Access Tokens + + +!!! note + To create a personal access token you need a running frontend. -As soon as you have a PAT (Personal Access Token) you can authenticate without -the application frontend. +Find more information about authentication with personal access tokens in the +user documentation: [Authentication](/api/index.md) -## Authentication without Application Frontend +## Bearer Token Request the `auth_url` diff --git a/docs/docs/development/docs.md b/docs/docs/development/docs.md index d2bda2f2c0..2a75494bd4 100644 --- a/docs/docs/development/docs.md +++ b/docs/docs/development/docs.md @@ -5,19 +5,85 @@ # Documentation -Write documentation if necessary so that developer, administrators and users -have an easily accessible way of learning about the collaboration manager. +It's important to have a good and up to date documentation for the +Collaboration Manager. Documentation is an accessible way to share knowledge +for developers, administrators and users. It can also be used by support teams +to resolve issues more efficiently. -## Setup and Serve the Documentation +## Development Setup Navigate to the `docs` folder. With the commands `make install` and `make serve` you can build the documentation and find it served under -`http://127.0.0.1:8081/`. Here you can try your newly written documentation or -search for something yourself. +`http://127.0.0.1:8081/`. It's a live-preview of the current version and does +automatically refresh on file-changes. -## Titles +## Style guide + +### Titles When writing the documentation we are using title case in the -[`Chicago Manual of Style` style](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style). +[`Chicago Manual of Style`](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style). In addition personal names/ names of packages are written according to their documentation. + +### Tree structure + +The documentation is split into three main sections, each with its own +subsections: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PathNameDescription
/userUser documentation + For users of the Collaboration Manager. It contains information about how to use the platform and its features. + The content shall be written in a way that it is understandable for non-technical users. +
/user/projectProject documentation + This section shall describe how to create, update and delete projects. It also contains information about the project settings and the project access management, as well as backup pipelines, tool models, diagram cache model sources and the model complexity badge. +
/user/sessionsSessions documentation + Describes tool indepdentend session features. It contains information how to create persistent and read-only sessions. + Tool specific features (e.g. TeamForCapella session tokens) don't belong here and should be documented in the tool section. +
/user/toolsTools documentation + Tool specific content belongs here. Examples are Capella related topics, for example the TeamForCapella and Git workflows. + Also Jupyter, Papyrus and `pure::variants` configurations shall be documented here. +
/apiAPI documentation + This section describes the external Collaboration Manager API usage. + The API documentation has it's own section, because it's relevant for developers, admins and users. +
/adminAdministrator documentationFor users of the Collaboration Manager. It contains information about how to use the platform and its features.
/developmentDevelopment documentationFor developers who want to contribute to the Collaboration Manager. It contains information about the development setup, the architecture and the code style.
diff --git a/docs/docs/index.md b/docs/docs/index.md index f57135cb48..eed08fa4e9 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -9,7 +9,9 @@ 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) +- If you want to automate tasks using our API, have a look at the + [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) + the platform: [Administrator documentation](./api/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/user/index.md b/docs/docs/user/index.md index c57e52c887..a5d788a197 100644 --- a/docs/docs/user/index.md +++ b/docs/docs/user/index.md @@ -115,10 +115,9 @@ 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-only project (not yet documented, contact your - toolchain team for onboarding) +- [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/) ## Missing Information / Need Support diff --git a/docs/docs/user/projects/access.md b/docs/docs/user/projects/access.md index b00cf4a826..4a1627ae26 100644 --- a/docs/docs/user/projects/access.md +++ b/docs/docs/user/projects/access.md @@ -16,5 +16,5 @@ Your project manager can find more information here: You can verify access by navigating to `Projects`. You should see the project now: ![Project overview](access/project-overview.png) If you want to verify if the persistent session with the TeamForCapella access works, you can follow the -[TeamForCapella workflow](../sessions/flows/t4c.md). The model should be listed -in the connection dialog. +[TeamForCapella workflow](../tools/capella/teamforcapella/connect/connect-to-t4c.md). +The model should be listed in the connection dialog. diff --git a/docs/docs/user/projects/models/metadata.md b/docs/docs/user/projects/models/metadata.md index 49db13288a..ff50d8b0d7 100644 --- a/docs/docs/user/projects/models/metadata.md +++ b/docs/docs/user/projects/models/metadata.md @@ -7,7 +7,8 @@ !!! warning - Make sure to read the documentation about updating a [TeamForCapella model](../../tools/capella/teamforcapella/update.md) or about updating a [Capella model](../../tools/capella/update.md) first! + Make sure to read the documentation about updating a [TeamForCapella model](/admin/teamforcapella/migration/update.md) + or about updating a [Capella model](../../tools/capella/migration/update.md) first! 1. Navigate to `Projects` and select the project. 1. In the model overview and select the :material-cog: icon on model you'd like diff --git a/docs/docs/user/sessions/reconnect.md b/docs/docs/user/sessions/reconnect.md index 4c840f2b97..77642e36f4 100644 --- a/docs/docs/user/sessions/reconnect.md +++ b/docs/docs/user/sessions/reconnect.md @@ -14,5 +14,5 @@ 5. Please follow the instructions (depends on the workflow of your project) - 1. [Git](flows/git.md) - 2. [TeamForCapella](flows/t4c.md) + 1. [Git](../tools/capella/git/working-with-git.md) + 2. [TeamForCapella](../tools/capella/teamforcapella/connect/connect-to-t4c.md) diff --git a/docs/docs/user/sessions/troubleshooting.md b/docs/docs/user/sessions/troubleshooting.md index 0f995c02ea..2d43e0c97c 100644 --- a/docs/docs/user/sessions/troubleshooting.md +++ b/docs/docs/user/sessions/troubleshooting.md @@ -47,7 +47,7 @@ ??? question "The TeamForCapella password doesn't work" Since we have released version 2, users have to use sessions passwords. More - information can be found [here](./flows/t4c.md). + information can be found [here](../tools/capella/teamforcapella/connect/connect-to-t4c.md). If you have been added to a project recently while having a running session, please recreate your session to get a valid session password for the models of the required project. diff --git a/docs/docs/user/sessions/types/persistent.md b/docs/docs/user/sessions/types/persistent.md index 61dae54672..f855b9f453 100644 --- a/docs/docs/user/sessions/types/persistent.md +++ b/docs/docs/user/sessions/types/persistent.md @@ -24,12 +24,12 @@ !!! info You can find your TeamForCapella session password in the connection - dialog. Please follow the [`TeamForCapella` guide](../flows/t4c.md) + dialog. Please follow the [`TeamForCapella` guide](../..//tools/capella/teamforcapella/connect/connect-to-t4c.md) for more information. 5. When Capella is loaded you can start working. !!! info "Do you need access to a TeamForCapella model?" - Please continue with the [Connect to a `TeamForCapella` repository guide](../flows/t4c.md). + Please continue with the [Connect to a `TeamForCapella` repository guide](../../tools/capella/teamforcapella/connect/connect-to-t4c.md). diff --git a/docs/docs/user/tokens.md b/docs/docs/user/tokens.md deleted file mode 100644 index 54c2dd5dd4..0000000000 --- a/docs/docs/user/tokens.md +++ /dev/null @@ -1,63 +0,0 @@ - - -# Authentication with Personal Access Tokens (PAT) - -To authenticate against the API you can either use a Bearer token (which the -browser usually uses) or authenticate with a longer lived personal access token -(PAT) which can be used e.g. in scripts. - -## PAT Creation - -To create a personal access token (PAT) you can go to Profile > Token and -insert a short description and pick a date until when the token should be -valid. - - -!!! info - The password which is generated can only be copied once. Make sure you save - it - you won't be able to access it again - -## PAT Scope - -Personal access token have the same scope as the user who created it. It is -therefore important that you never pass on the token and treat it responsibly. -If you feel that the token has been lost, revoke it immediately and inform the -Systems Engineering Toolchain team. - -## Revoke a PAT - -In order to revoke a token go to Profile > Token. There you can see a list of -all tokens that belong to your user. By clicking on the trash symbol, you can -delete a token, which will no longer be valid for authentication. - -## PAT Usage - -The token created is a personal access token. There are different ways to -authenticate with that against the Collaboration Manager API. One example is: - -```zsh -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 -[documentation](https://dsd-dbs.github.io/py-capellambse/) or the -[Github repository](https://github.com/DSD-DBS/py-capellambse). - -```python -model = capellambse.model.MelodyModel( - path="", - diagram_cache={ - "path": "https:///api/v1/projects//models//diagrams/%s", - "username": "", - "password": "", - } -) -``` - -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/configure-merge-direction.png b/docs/docs/user/tools/capella/git/screenshots/configure-merge-direction.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/configure-merge-direction.png rename to docs/docs/user/tools/capella/git/screenshots/configure-merge-direction.png diff --git a/docs/docs/user/tools/capella/working-with-git/configure-merge-direction.png.license b/docs/docs/user/tools/capella/git/screenshots/configure-merge-direction.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/configure-merge-direction.png.license rename to docs/docs/user/tools/capella/git/screenshots/configure-merge-direction.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/configure-merge-matching.png b/docs/docs/user/tools/capella/git/screenshots/configure-merge-matching.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/configure-merge-matching.png rename to docs/docs/user/tools/capella/git/screenshots/configure-merge-matching.png diff --git a/docs/docs/user/tools/capella/working-with-git/configure-merge-matching.png.license b/docs/docs/user/tools/capella/git/screenshots/configure-merge-matching.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/configure-merge-matching.png.license rename to docs/docs/user/tools/capella/git/screenshots/configure-merge-matching.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/create-merge-branch.png b/docs/docs/user/tools/capella/git/screenshots/create-merge-branch.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/create-merge-branch.png rename to docs/docs/user/tools/capella/git/screenshots/create-merge-branch.png diff --git a/docs/docs/user/tools/capella/working-with-git/create-merge-branch.png.license b/docs/docs/user/tools/capella/git/screenshots/create-merge-branch.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/create-merge-branch.png.license rename to docs/docs/user/tools/capella/git/screenshots/create-merge-branch.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/explain-merge-view.png b/docs/docs/user/tools/capella/git/screenshots/explain-merge-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/explain-merge-view.png rename to docs/docs/user/tools/capella/git/screenshots/explain-merge-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/explain-merge-view.png.license b/docs/docs/user/tools/capella/git/screenshots/explain-merge-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/explain-merge-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/explain-merge-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/local-destination.png b/docs/docs/user/tools/capella/git/screenshots/local-destination.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/local-destination.png rename to docs/docs/user/tools/capella/git/screenshots/local-destination.png diff --git a/docs/docs/user/tools/capella/working-with-git/local-destination.png.license b/docs/docs/user/tools/capella/git/screenshots/local-destination.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/local-destination.png.license rename to docs/docs/user/tools/capella/git/screenshots/local-destination.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/merge-decide-side.png b/docs/docs/user/tools/capella/git/screenshots/merge-decide-side.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/merge-decide-side.png rename to docs/docs/user/tools/capella/git/screenshots/merge-decide-side.png diff --git a/docs/docs/user/tools/capella/working-with-git/merge-decide-side.png.license b/docs/docs/user/tools/capella/git/screenshots/merge-decide-side.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/merge-decide-side.png.license rename to docs/docs/user/tools/capella/git/screenshots/merge-decide-side.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/open-reset-view.png b/docs/docs/user/tools/capella/git/screenshots/open-reset-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/open-reset-view.png rename to docs/docs/user/tools/capella/git/screenshots/open-reset-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/open-reset-view.png.license b/docs/docs/user/tools/capella/git/screenshots/open-reset-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/open-reset-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/open-reset-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/reset-hard-view.png b/docs/docs/user/tools/capella/git/screenshots/reset-hard-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/reset-hard-view.png rename to docs/docs/user/tools/capella/git/screenshots/reset-hard-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/reset-hard-view.png.license b/docs/docs/user/tools/capella/git/screenshots/reset-hard-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/reset-hard-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/reset-hard-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/search-git-repository-view.png b/docs/docs/user/tools/capella/git/screenshots/search-git-repository-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/search-git-repository-view.png rename to docs/docs/user/tools/capella/git/screenshots/search-git-repository-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/search-git-repository-view.png.license b/docs/docs/user/tools/capella/git/screenshots/search-git-repository-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/search-git-repository-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/search-git-repository-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/search-view.png b/docs/docs/user/tools/capella/git/screenshots/search-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/search-view.png rename to docs/docs/user/tools/capella/git/screenshots/search-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/search-view.png.license b/docs/docs/user/tools/capella/git/screenshots/search-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/search-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/search-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/staged-changes.png b/docs/docs/user/tools/capella/git/screenshots/staged-changes.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/staged-changes.png rename to docs/docs/user/tools/capella/git/screenshots/staged-changes.png diff --git a/docs/docs/user/tools/capella/working-with-git/staged-changes.png.license b/docs/docs/user/tools/capella/git/screenshots/staged-changes.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/staged-changes.png.license rename to docs/docs/user/tools/capella/git/screenshots/staged-changes.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/start-compare-view.png b/docs/docs/user/tools/capella/git/screenshots/start-compare-view.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/start-compare-view.png rename to docs/docs/user/tools/capella/git/screenshots/start-compare-view.png diff --git a/docs/docs/user/tools/capella/working-with-git/start-compare-view.png.license b/docs/docs/user/tools/capella/git/screenshots/start-compare-view.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/start-compare-view.png.license rename to docs/docs/user/tools/capella/git/screenshots/start-compare-view.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/switch-branch-v1.png b/docs/docs/user/tools/capella/git/screenshots/switch-branch-v1.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/switch-branch-v1.png rename to docs/docs/user/tools/capella/git/screenshots/switch-branch-v1.png diff --git a/docs/docs/user/tools/capella/working-with-git/switch-branch-v1.png.license b/docs/docs/user/tools/capella/git/screenshots/switch-branch-v1.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/switch-branch-v1.png.license rename to docs/docs/user/tools/capella/git/screenshots/switch-branch-v1.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/switch-branch-v2.png b/docs/docs/user/tools/capella/git/screenshots/switch-branch-v2.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/switch-branch-v2.png rename to docs/docs/user/tools/capella/git/screenshots/switch-branch-v2.png diff --git a/docs/docs/user/tools/capella/working-with-git/switch-branch-v2.png.license b/docs/docs/user/tools/capella/git/screenshots/switch-branch-v2.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/switch-branch-v2.png.license rename to docs/docs/user/tools/capella/git/screenshots/switch-branch-v2.png.license diff --git a/docs/docs/user/tools/capella/working-with-git/unstaged-changes.png b/docs/docs/user/tools/capella/git/screenshots/unstaged-changes.png similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/unstaged-changes.png rename to docs/docs/user/tools/capella/git/screenshots/unstaged-changes.png diff --git a/docs/docs/user/tools/capella/working-with-git/unstaged-changes.png.license b/docs/docs/user/tools/capella/git/screenshots/unstaged-changes.png.license similarity index 100% rename from docs/docs/user/tools/capella/working-with-git/unstaged-changes.png.license rename to docs/docs/user/tools/capella/git/screenshots/unstaged-changes.png.license diff --git a/docs/docs/user/tools/capella/working-with-git.md b/docs/docs/user/tools/capella/git/working-with-git.md similarity index 91% rename from docs/docs/user/tools/capella/working-with-git.md rename to docs/docs/user/tools/capella/git/working-with-git.md index 851b4eb555..922c34dfaa 100644 --- a/docs/docs/user/tools/capella/working-with-git.md +++ b/docs/docs/user/tools/capella/git/working-with-git.md @@ -15,11 +15,11 @@ that collegues can see and review them. First open the View _Git Repository_ by clicking on the magnifying glass (1) in the right corner. -![Step 1: Open View Search](working-with-git/search-view.png) +![Step 1: Open View Search](screenshots/search-view.png) Searching looks like: -![Step 2: Search for View](working-with-git/search-git-repository-view.png) +![Step 2: Search for View](screenshots/search-git-repository-view.png) When clicking "Clone a Git repository" a view "Source Git Repository" to enter the repository url opens. Enter here the URL of the _Remote_ of your repository @@ -33,7 +33,7 @@ Destination" opens. This shows where your work is going to be stored locally. Tick the box: "Import all existing Eclipse projects after clone finishes" importing the cloned repository into your eclipse workspace -![Step 3: Local Destination](working-with-git/local-destination.png) +![Step 3: Local Destination](screenshots/local-destination.png) Then you can click finish. Your repository from the _Remote_ is now cloned locally. @@ -47,12 +47,12 @@ new one). Either you right click on the project name in the lower right corner, go to "Switch to" and then e.g. "New Branch" -![Step 4: Search for View](working-with-git/switch-branch-v1.png) +![Step 4: Search for View](screenshots/switch-branch-v1.png) or you can right click on the project name in the project tree and then click "Team"> "Switch to" > "New Branch". -![Step 5: Search for View](working-with-git/switch-branch-v2.png) +![Step 5: Search for View](screenshots/switch-branch-v2.png) In order to make the changes visible in your project tree and to see on which branch you are currently working on right click on the project name > "Close @@ -68,7 +68,7 @@ changes that you made in the file tree on the left indicated by ">" (2). If there are no (un-)staged changes you did not make a change compared to the last state that Git already has saved in commits. -![Step 6: Search for View](working-with-git/unstaged-changes.png) +![Step 6: Search for View](screenshots/unstaged-changes.png) In the _Git Staging_ View mark the unstaged files that you want to stage and drag them with your mouse to the "Staged Changes" area. Then reload (3) the @@ -95,7 +95,7 @@ changes (2). !!! info The commit is now made locally. In order to publish it and share it with other you have to push it to the *Remote*! -![Step 7: Search for View](working-with-git/staged-changes.png) +![Step 7: Search for View](screenshots/staged-changes.png) If you already committed your changes you can right click on the Project > "Team" > "Push to Origin" in order to push your changes to the remote. @@ -122,7 +122,7 @@ also diff two models on your own in order to check which changes were made. Therefore, select both `.aird`-files (e.g. with control click). Then right click on one of the files and select "Compare with" > "Each other as model". -![Open compare View](working-with-git/start-compare-view.png) +![Open compare View](screenshots/start-compare-view.png) In the image you can see the [coffee machine model](https://github.com/DSD-DBS/coffee-machine) imported @@ -138,7 +138,7 @@ the target, and are going to change the target model. Make sure to select the correct direction of merging in order to modify the correct model. -![Configure Merge Direction](working-with-git/configure-merge-direction.png) +![Configure Merge Direction](screenshots/configure-merge-direction.png) In the example we want to merge our changes from Left (coffee-machine model on working branch) into Right (coffee machine model on main branch)(1). @@ -157,7 +157,7 @@ and "Diagrams: Match remaining shapes according to type" as in Diagrams IDs might change just by opening them. If nothing else helps choose "Names" and click "Use labels as names" to match but labels easily change. -![Configure Matching Strategie](working-with-git/configure-merge-matching.png) +![Configure Matching Strategie](screenshots/configure-merge-matching.png) Afterwards, click "Ok" and "Finish". @@ -166,7 +166,7 @@ is going to be modified. They are also labeled as source and target where the source is from which we are taking the changes and the target is the model that gets modified. -![Explain Merge View](working-with-git/explain-merge-view.png) +![Explain Merge View](screenshots/explain-merge-view.png) The colors highlight what change was made and will be applied to the target if you apply the change: _blue: create, red: delete, purple: modify_. @@ -219,7 +219,7 @@ as a user have to decide which changes to keep. In the following we are describing how you can pick the changes that you later want to see in the model. -![Decide Side of Change](working-with-git/merge-decide-side.png) +![Decide Side of Change](screenshots/merge-decide-side.png) With the butttons above the details of the made changes enable us to decide the change from which model to take and which change to discard. @@ -237,11 +237,11 @@ opportunistic in merging layouts. If merging with the merge tool is not possible you have to open the reset view. -![Step 8: Open Reset View](working-with-git/open-reset-view.png){:style="width:500px"} +![Step 8: Open Reset View](screenshots/open-reset-view.png){:style="width:500px"} Then select hard reset of your local branch: -![Step 9: Git Reset Hard](working-with-git/reset-hard-view.png) +![Step 9: Git Reset Hard](screenshots/reset-hard-view.png) If you committed your changes earlier, and select your local main branch as described, your local files will be reset to the state they were in after your @@ -257,7 +257,7 @@ right click on the project > "Team" > "Push branch 'main'...". In the view “merge-branch-name” (1) and remove the “configure upstream push and pull” (2) option. -![Step 10: Git Create Intermediate Branch](working-with-git/create-merge-branch.png) +![Step 10: Git Create Intermediate Branch](screenshots/create-merge-branch.png) After pushing your changes to the remote Git repository, open the remote project on Gitlab or Github. Then open a Merge request (Gitlab) or Pull request diff --git a/docs/docs/user/tools/capella/teamforcapella/backup-migration.png b/docs/docs/user/tools/capella/migration/backup-migration.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/backup-migration.png rename to docs/docs/user/tools/capella/migration/backup-migration.png diff --git a/docs/docs/user/tools/capella/teamforcapella/backup-migration.png.license b/docs/docs/user/tools/capella/migration/backup-migration.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/backup-migration.png.license rename to docs/docs/user/tools/capella/migration/backup-migration.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/migrate-capella-model.png b/docs/docs/user/tools/capella/migration/migrate-capella-model.png similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/migrate-capella-model.png rename to docs/docs/user/tools/capella/migration/migrate-capella-model.png diff --git a/docs/docs/user/tools/capella/teamforcapella/migrate-capella-model.png.license b/docs/docs/user/tools/capella/migration/migrate-capella-model.png.license similarity index 100% rename from docs/docs/user/tools/capella/teamforcapella/migrate-capella-model.png.license rename to docs/docs/user/tools/capella/migration/migrate-capella-model.png.license diff --git a/docs/docs/user/tools/capella/update.md b/docs/docs/user/tools/capella/migration/update.md similarity index 66% rename from docs/docs/user/tools/capella/update.md rename to docs/docs/user/tools/capella/migration/update.md index 880c55459a..8a1e22a07e 100644 --- a/docs/docs/user/tools/capella/update.md +++ b/docs/docs/user/tools/capella/migration/update.md @@ -12,19 +12,20 @@ !!! info - If you want to update a Capella model saved in TeamForCapella, please follow the Capella specific instructions instead: - [Update a TeamForCapella based Capella model](../../tools/capella/teamforcapella/update.md) + If you want to update a Capella model saved in TeamForCapella, please follow the TeamForCapella specific instructions instead: + [Update a TeamForCapella based Capella model](/admin/teamforcapella/migration/update.md). + An administrator is required to update the Capella version in TeamForCapella. 1. Open a new persistent session with the old Capella version. 1. Import the model into your workspace. 1. Terminate the session. 1. Update the model version to the newer Capella version: - [Change model metadata](../../projects/models/metadata.md) + [Change model metadata](../../../projects/models/metadata.md). 1. Create a new session with the new Capella version. 1. In your persistent workspace loaded, execute the following steps: 1. Right click on the model in your workspace. 1. Select `Migration` and `Migrate Project toward current version` - ![Migrate Capella model](../../tools/capella/teamforcapella/migrate-capella-model.png) - 1. A backup is recommended. - ![Disable backup option](../../tools/capella/teamforcapella/backup-migration.png) + ![Migrate Capella model](./migrate-capella-model.png) + 1. A backup is recommended. + ![Enable backup option](./backup-migration.png) diff --git a/docs/docs/user/tools/capella/teamforcapella/add-repository.png b/docs/docs/user/tools/capella/teamforcapella/add-repository.png deleted file mode 100644 index a674757d29..0000000000 Binary files a/docs/docs/user/tools/capella/teamforcapella/add-repository.png and /dev/null differ diff --git a/docs/docs/user/tools/capella/teamforcapella/add-repository.png.license b/docs/docs/user/tools/capella/teamforcapella/add-repository.png.license deleted file mode 100644 index 7ea22469b1..0000000000 --- a/docs/docs/user/tools/capella/teamforcapella/add-repository.png.license +++ /dev/null @@ -1,2 +0,0 @@ -SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors -SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/user/sessions/flows/t4c.md b/docs/docs/user/tools/capella/teamforcapella/connect/connect-to-t4c.md similarity index 93% rename from docs/docs/user/sessions/flows/t4c.md rename to docs/docs/user/tools/capella/teamforcapella/connect/connect-to-t4c.md index 41ce7ce97e..1e19d1b36e 100644 --- a/docs/docs/user/sessions/flows/t4c.md +++ b/docs/docs/user/tools/capella/teamforcapella/connect/connect-to-t4c.md @@ -9,7 +9,7 @@ !!! Info Connecting to a T4C model in that way will open a connection and automatically write changes back to the T4C model. If you do not want to write changes back you can follow - [the import T4C model](../../tools/capella/teamforcapella/import/import-from-t4c.md) + [the import T4C model](../import/import-from-t4c.md) tutorial To access a TeamForCapella based model you first need read/write access from a @@ -17,7 +17,7 @@ model lead (usually this role is allocated to lead architects / area owners). !!! Info - Please [request a persistent session](../request.md) before you continue + Please [request a persistent session](../../../../sessions/request.md) before you continue with the instructions here. diff --git a/docs/docs/user/sessions/flows/screenshots/cap-test-conn.jpg b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/cap-test-conn.jpg similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/cap-test-conn.jpg rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/cap-test-conn.jpg diff --git a/docs/docs/user/sessions/flows/screenshots/cap-test-conn.jpg.license b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/cap-test-conn.jpg.license similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/cap-test-conn.jpg.license rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/cap-test-conn.jpg.license diff --git a/docs/docs/user/sessions/flows/screenshots/connection-example.jpg b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/connection-example.jpg similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/connection-example.jpg rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/connection-example.jpg diff --git a/docs/docs/user/sessions/flows/screenshots/connection-example.jpg.license b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/connection-example.jpg.license similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/connection-example.jpg.license rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/connection-example.jpg.license diff --git a/docs/docs/user/sessions/flows/screenshots/session-token.png b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/session-token.png similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/session-token.png rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/session-token.png diff --git a/docs/docs/user/sessions/flows/screenshots/session-token.png.license b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/session-token.png.license similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/session-token.png.license rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/session-token.png.license diff --git a/docs/docs/user/sessions/flows/screenshots/step_1.png b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_1.png similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/step_1.png rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_1.png diff --git a/docs/docs/user/sessions/flows/screenshots/step_1.png.license b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_1.png.license similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/step_1.png.license rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_1.png.license diff --git a/docs/docs/user/sessions/flows/screenshots/step_2.png b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_2.png similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/step_2.png rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_2.png diff --git a/docs/docs/user/sessions/flows/screenshots/step_2.png.license b/docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_2.png.license similarity index 100% rename from docs/docs/user/sessions/flows/screenshots/step_2.png.license rename to docs/docs/user/tools/capella/teamforcapella/connect/screenshots/step_2.png.license diff --git a/docs/docs/user/tools/capella/teamforcapella/export/export-to-t4c.md b/docs/docs/user/tools/capella/teamforcapella/export/export-to-t4c.md index 49f1077011..1e54b867c5 100644 --- a/docs/docs/user/tools/capella/teamforcapella/export/export-to-t4c.md +++ b/docs/docs/user/tools/capella/teamforcapella/export/export-to-t4c.md @@ -19,8 +19,8 @@ select `Capella Project to Remote Repository` and confirm with `Next`: ![Capella Project to Remote Repository](./capella-project-to-repository.png) 1. Select the repository from the dropdown menu. Click on the `Test connection` - button and enter your [session token](../../../../sessions/flows/t4c.md). - Click on `Next`. + button and enter your [session token](../connect/connect-to-t4c.md). Click + on `Next`. ![Select repository for export](./export-repository-selection.png) 1. Select the overwrite strategy. If the project doesn't exist on the server yet, choose `Replace`. Otherwise, select `Merge`. diff --git a/docs/docs/user/tools/capella/teamforcapella/import/import-from-t4c.md b/docs/docs/user/tools/capella/teamforcapella/import/import-from-t4c.md index 7a480de07b..c302283adf 100644 --- a/docs/docs/user/tools/capella/teamforcapella/import/import-from-t4c.md +++ b/docs/docs/user/tools/capella/teamforcapella/import/import-from-t4c.md @@ -14,7 +14,7 @@ !!! info This imports a model into your workspace and changes are not automatically saved back to the T4C repository. If you want to save changes directly back to the server - use [this](../../../../sessions/flows/t4c.md) documentation. + use [this](../connect/connect-to-t4c.md) documentation. 1. Open a persistent session with the corresponding Capella version. 1. Wait until Capella has started. @@ -25,7 +25,7 @@ confirm with `Next`. ![Import project from remote repository](./project-from-remote-repository.png) 1. Select the repository from the dropdown menu. Click on the `Test connection` - button and enter your [session token](../../../../sessions/flows/t4c.md). + button and enter your [session token](../connect/connect-to-t4c.md). ![Select repository for import](./import-repository-selection.png) 1. Click on `Next` . diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1ca183e13f..013ce8d14b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -23,8 +23,6 @@ nav: - Models: - Create a Model: user/projects/models/create.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 @@ -42,42 +40,42 @@ nav: - (Re-)Connect to Session: user/sessions/reconnect.md - Terminate Session: user/sessions/terminate.md - Taking Screenshots: user/sessions/screenshot/screenshots.md - - Flows: - - Git: user/sessions/flows/git.md - - TeamForCapella: user/sessions/flows/t4c.md - Files Browser: user/sessions/files/files.md - Troubleshooting: user/sessions/troubleshooting.md - - Jupyter: - - Collaboration: user/sessions/jupyter/collaboration.md - - Tools: - - Capella: - - Introduction: user/tools/capella/introduction.md - - Update a Capella Model to a Newer Version: user/tools/capella/update.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 - - TeamForCapella Project Management: user/tools/capella/teamforcapella/project-management/project-management.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 + - Capella: + - Introduction: user/tools/capella/introduction.md + - Update a Capella Model to a Newer Version: user/tools/capella/migration/update.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 + - Git: + - Working with Git: user/tools/capella/git/working-with-git.md + - Jupyter: + - Collaboration: user/sessions/jupyter/collaboration.md + - API documentation: + - Introduction: api/index.md + - api/swaggerui.md + - api/redoc.md + - api/openapi.md - Administrator Documentation: - Index: admin/index.md - Installation: admin/installation.md - Uninstallation: admin/uninstallation.md - Getting started: admin/getting_started/getting_started.md - - Settings: - - Monitoring: admin/settings/monitoring.md - - Tools: - - General: admin/settings/tools/index.md - - pure::variants: admin/settings/tools/pure_variants.md - - Model sources: - - Git: admin/settings/model-sources/git.md - - T4C: admin/settings/model-sources/t4c.md - - Alerts: - - Create an Alert: admin/alerts/create.md + - Integrations: + - Git: admin/settings/model-sources/git.md + - TeamForCapella: + - Manage T4C Instances: admin/settings/model-sources/t4c.md + - Full Setup Guide: admin/teamforcapella/full-setup/full-setup.md + - TeamForCapella Repository Management: admin/teamforcapella/repository-management/repository-management.md + - TeamForCapella Project Management: admin/teamforcapella/project-management/project-management.md + - Link a TeamForCapella Repository: admin/teamforcapella/project-integration/project-integration.md + - Update a TeamForCapella-based Model: admin/teamforcapella/migration/update.md + - pure::variants: admin/settings/tools/pure_variants.md + - Tools: admin/settings/tools/index.md + - Alerts: admin/alerts/create.md + - Monitoring: admin/settings/monitoring.md - CI templates: - Gitlab CI/CD: - Image builder: admin/ci-templates/gitlab/image-builder.md diff --git a/helm/config/nginx.conf b/helm/config/nginx.conf index 632adc4f69..535594c46b 100644 --- a/helm/config/nginx.conf +++ b/helm/config/nginx.conf @@ -22,7 +22,7 @@ http { return 200 "healthy"; } - location /api/v1/ { + location /api/ { client_max_body_size 30m; proxy_pass http://{{ .Release.Name }}-backend:80; proxy_redirect http://{{ .Release.Name }}-backend {{ .Values.general.scheme }}://{{ .Values.general.host }}:{{ .Values.general.port }}; diff --git a/helm/templates/routing/nginx.ingress.yaml b/helm/templates/routing/nginx.ingress.yaml index 8164c23cef..606061152b 100644 --- a/helm/templates/routing/nginx.ingress.yaml +++ b/helm/templates/routing/nginx.ingress.yaml @@ -24,7 +24,7 @@ spec: name: {{ .Release.Name }}-frontend port: number: 80 - - path: /api/v1 + - path: /api pathType: Prefix backend: service: diff --git a/helm/templates/routing/nginx.route.openshift.yaml b/helm/templates/routing/nginx.route.openshift.yaml index 62722eff84..4420589ca5 100644 --- a/helm/templates/routing/nginx.route.openshift.yaml +++ b/helm/templates/routing/nginx.route.openshift.yaml @@ -3,7 +3,7 @@ {{- if eq .Values.cluster.kind "OpenShift" }} {{ $frontend := dict "path" "/" "service" "frontend" "targetPort" "http" }} -{{ $backend := dict "path" "/api/v1" "service" "nginx-clusterip" "targetPort" "http" }} +{{ $backend := dict "path" "/api" "service" "nginx-clusterip" "targetPort" "http" }} {{ $docs := dict "path" "/docs" "service" "docs" "targetPort" "http" }} {{ $guacamole := dict "path" "/guacamole" "service" "guacamole-guacamole" "targetPort" "http" }} {{ $prometheus := dict "path" "/prometheus" "service" "prometheus-nginx" "targetPort" "promui" }}