docs: Expose "API documentation" and restructure users docs

- A new section "API documentation" is added; PAT and authentication information
  is moved to the new section.
- The new API documentation has a new Python example.
- The new section has a link to the OpenAPI documentation, which in only
  accessible for running Collaboration Manager instances.
- The OpenAPI documentation uses the correct auto-determined version now (before it was 0.1.0)
- The Path to the documentation has changes, a prefix `/api/docs` was added,
  a redirect from the old `/docs` route is in place.
- The "Tools" abstraction layer was removed in the tree.
  Instead, Capella & Jupyter have top level sections now.
  The goal is to increase visibility for the Capella section, which is frequently used.
- "Flows" has been removed from the "Sessions" section; sessions will focus
  on tool independent topics; T4C flow is moved to "Capella" section
- The Git workflow and API documentation are now mentioned in the Introduction
  of the user docs
- For consistency, the Git workflow has it's own folder in the Capella section now
  (like T4C also has)
- A full T4C setup guide was added, describing the creation of a T4C based project,
  from project creation to diagram cache setup.
- Some general grammar & style improvements.
- Old references to `Profile` are updated to `Menu`
- Administrative T4C pages are moved to the admin section.

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)
 
 

docs/docs/admin/alerts/create.md

@@ -3,16 +3,12 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-<!-- prettier-ignore -->
-!!! 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.
 
 <!-- prettier-ignore-start -->
 
-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)
 

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

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`

docs/docs/admin/teamforcapella/full-setup/full-setup.md

@@ -0,0 +1,23 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# 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!

docs/docs/user/tools/capella/teamforcapella/update.md → 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:
    <!-- prettier-ignore -->
     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)

docs/docs/user/projects/models/sources/t4c.md → docs/docs/admin/teamforcapella/project-integration/project-integration.md

@@ -5,13 +5,9 @@
 
 # Manage the TeamForCapella Project Integration
 
-<!-- prettier-ignore -->
-!!! 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. <br /> ![Model sources](./open-modelsources.png)
+sources button for the model. <br />
+![Model sources](./screenshots/open-modelsources.png)
 
 ## Link a TeamForCapella Repository to a Project Model
 

docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md → 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.
-
 <!-- prettier-ignore -->
 1. Open a persistent Capella session and connect to it.
 1. Enable the TeamForCapella administration capability: <br /> `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)

docs/docs/user/tools/capella/teamforcapella/repository-management.md → docs/docs/admin/teamforcapella/repository-management/repository-management.md

@@ -5,14 +5,10 @@
 
 # TeamForCapella Repository Management
 
-<!-- prettier-ignore -->
-!!! 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
 

docs/docs/api/index.md

@@ -0,0 +1,117 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# 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.
+
+<!-- prettier-ignore -->
+!!! 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)
+
+<!-- prettier-ignore -->
+!!! 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.
+
+<!-- prettier-ignore -->
+!!! 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="<path to the model on your machine>",
+  diagram_cache={
+    "path": "https://<your backend url>/api/v1/projects/<your project slug>/models/<your model slug>/diagrams/%s",
+    "username": "<username>",
+    "password": "<your PAT>",
+  }
+)
+```
+
+Having created a model like that you can e.g. with `model.diagrams[0]` get the
+first diagram.

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
+---
+
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->

docs/docs/user/sessions/flows/git.md → docs/docs/api/redoc.md

@@ -1,6 +1,11 @@
+---
+template: redirect.html
+location: /api/docs/redoc
+title: ReDoc
+icon: octicons/link-external-16
+---
+
 <!--
  ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
  ~ SPDX-License-Identifier: Apache-2.0
  -->
-
-The documentation for the Git workflow will follow in the future.

docs/docs/api/swaggerui.md

@@ -0,0 +1,11 @@
+---
+template: redirect.html
+location: /api/docs/openapi
+title: SwaggerUI
+icon: octicons/link-external-16
+---
+
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->

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
+
+<!-- prettier-ignore -->
+!!! 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`