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](../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/projects/models/sources/t4c.md → docs/docs/admin/teamforcapella/project-integration/project-integration.md

@@ -5,11 +5,6 @@
 
 # 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)
 

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

@@ -39,7 +39,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,14 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+---
+
+template: redirect.html
+
+location: /api/docs/openapi.json
+
+title: OpenAPI Specification icon: octicons/link-external-16
+
+---

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

@@ -3,4 +3,12 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-The documentation for the Git workflow will follow in the future.
+---
+
+template: redirect.html
+
+location: /api/docs/redoc
+
+title: ReDoc icon: octicons/link-external-16
+
+---

docs/docs/api/swaggerui.md

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

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`