From d89eda32218ce471a6aa17631d161bcb1fac5a07 Mon Sep 17 00:00:00 2001 From: Paula-Kli Date: Wed, 25 Oct 2023 14:35:25 +0200 Subject: [PATCH] refactor: Use title case in documentation --- .pre-commit-config.yaml | 1 - README.md | 10 ++++---- .../ci-templates/gitlab/image-builder.md | 4 ++-- .../admin/ci-templates/gitlab/k8s-deploy.md | 4 ++-- .../admin/getting_started/getting_started.md | 4 ++-- docs/docs/admin/installation.md | 18 +++++++-------- .../development/backend/authentication.md | 7 ++++-- docs/docs/development/backend/code-style.md | 2 +- .../development/backend/database-migration.md | 2 +- docs/docs/development/backend/exception.md | 2 +- docs/docs/development/backend/extensions.md | 2 +- docs/docs/development/docs.md | 23 +++++++++++++++++++ docs/docs/development/frontend/code-style.md | 4 ++-- docs/docs/development/frontend/customize.md | 2 +- docs/docs/development/frontend/routes.md | 2 +- docs/docs/development/frontend/testing.md | 16 ++++++------- docs/docs/development/index.md | 8 +++---- docs/docs/user/index.md | 6 ++--- docs/docs/user/projects/access.md | 2 +- docs/docs/user/projects/add-user.md | 4 ++-- docs/docs/user/projects/create.md | 8 +++---- .../user/projects/models/backups/remove.md | 2 +- .../user/projects/models/backups/setup.md | 2 +- .../user/projects/models/complexity_badge.md | 6 ++--- docs/docs/user/projects/models/create.md | 14 +++++------ .../models/diagrams/setup_diagram_cache.md | 2 +- .../models/diagrams/view_diagram_cache.md | 2 +- docs/docs/user/projects/models/metadata.md | 2 +- docs/docs/user/projects/models/sources/t4c.md | 6 ++--- docs/docs/user/projects/models/update.md | 2 +- docs/docs/user/sessions/files/files.md | 2 +- docs/docs/user/sessions/flows/t4c.md | 2 +- docs/docs/user/sessions/request.md | 2 +- .../user/sessions/screenshot/screenshots.md | 4 ++-- docs/docs/user/sessions/types.md | 2 +- docs/docs/user/sessions/types/persistent.md | 2 +- docs/docs/user/sessions/types/read-only.md | 2 +- docs/docs/user/settings/model-sources/git.md | 8 +++---- docs/docs/user/settings/model-sources/t4c.md | 6 ++--- docs/docs/user/settings/monitoring.md | 2 +- docs/docs/user/settings/tools/index.md | 4 ++-- .../docs/user/settings/tools/pure_variants.md | 12 +++++----- docs/docs/user/tools/capella/introduction.md | 4 ++-- .../user/tools/capella/t4c-git-compare.md | 6 ++--- .../teamforcapella/export/export-to-t4c.md | 2 +- .../teamforcapella/import/import-from-t4c.md | 2 +- .../project-management/project-management.md | 4 ++-- .../teamforcapella/repository-management.md | 8 +++---- .../tools/capella/teamforcapella/update.md | 2 +- .../user/tools/capella/working-with-git.md | 4 ++-- docs/mkdocs.yml | 1 + 51 files changed, 138 insertions(+), 112 deletions(-) create mode 100644 docs/docs/development/docs.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 03c911002a..211a65adc0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -73,7 +73,6 @@ repos: hooks: - id: prettier types_or: [ts, css, html, markdown] - files: "^frontend" additional_dependencies: - "prettier@^3.0.3" - "prettier-plugin-tailwindcss@^0.5.5" diff --git a/README.md b/README.md index 1e19543839..7b9e0b5c0b 100644 --- a/README.md +++ b/README.md @@ -52,9 +52,9 @@ In addition, we have integrated commercial products: - Automatic license injection - Access to licenses is self-managed by project leads -## Getting started +## Getting Started -### Running locally with k3d +### Running Locally with k3d #### Prerequisites @@ -78,7 +78,7 @@ When you have all that installed you can do the following: git clone --recurse-submodules https://github.com/DSD-DBS/capella-collab-manager.git cd capella-collab-manager -# Create a local k3d cluster +# Create a Local k3d Cluster make create-cluster ``` @@ -136,7 +136,7 @@ make delete-cluster k3d registry delete k3d-myregistry.localhost ``` -#### Starting a session +#### Starting a Session Once the cluster is installed and all services are running (`kubectl get pods`), you can get started. Follow our [Getting started guide](docs/getting_started/getting_started.md) and be up and @@ -146,7 +146,7 @@ running in a few minutes. You can find the installation guide for the deployment in the [general documentation](https://capella-collaboration-manager.readthedocs.io/en/latest/installation/). -## How it works +## How it Works The Capella Collaboration Manager consists of a couple of components: diff --git a/docs/docs/admin/ci-templates/gitlab/image-builder.md b/docs/docs/admin/ci-templates/gitlab/image-builder.md index 2a9f3ff915..5f4b42678a 100644 --- a/docs/docs/admin/ci-templates/gitlab/image-builder.md +++ b/docs/docs/admin/ci-templates/gitlab/image-builder.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Image builder (Gitlab CI/CD) +# Image Builder (Gitlab CI/CD) The image builder template builds the following images and pushes them to any Docker registry: @@ -50,7 +50,7 @@ please refer to the [image-builder](https://github.com/DSD-DBS/capella-collab-manager/blob/main/ci-templates/gitlab/image-builder.yml) Gitlab template. -### Docker SOPS file +### Docker SOPS File We make use of [Mozilla SOPS](https://github.com/mozilla/sops) files to store secrets used in the image builder template. Therefore you need to have a diff --git a/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md b/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md index 9ed974d5fd..0180a3d22c 100644 --- a/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md +++ b/docs/docs/admin/ci-templates/gitlab/k8s-deploy.md @@ -31,7 +31,7 @@ In addition you can adjust the following variables when running a pipeline: - `REVISION`: The revision of the capella collab manager repository you want to use -### Docker and Kubernetes sops files +### Docker and Kubernetes SOPS Files For the `k8s-deploy.yml` you need to have some secret sops files in place. First of all, you need a `secret.docker.json` file as described @@ -57,7 +57,7 @@ the `_unencrypted` suffix in the variable names). Please delete the plain text files containing secrets directly after encrypting them. -## Gitlab repository tree +## Gitlab Repository Tree The tree inside of your Gitlab repository should look like: diff --git a/docs/docs/admin/getting_started/getting_started.md b/docs/docs/admin/getting_started/getting_started.md index c58e99e631..37774aa1d4 100644 --- a/docs/docs/admin/getting_started/getting_started.md +++ b/docs/docs/admin/getting_started/getting_started.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Getting started +# Getting Started This guide describes the steps to get started with the Capella Collaboration Manager. @@ -40,7 +40,7 @@ workspace will be shown in your browser. ![Capella welcome screen](img/collab-step-5.png) -## What's next +## What's Next This introduction only scratches the surface of what's possible with the Collaboration Manager. diff --git a/docs/docs/admin/installation.md b/docs/docs/admin/installation.md index 9b281ad1b9..9640c69572 100644 --- a/docs/docs/admin/installation.md +++ b/docs/docs/admin/installation.md @@ -14,7 +14,7 @@ During development, we also took into account that the application can be installed in highly restricted environments. An internet connection is not necessarily required. -## Step 1: Set up a Kubernetes cluster +## Step 1: Set up a Kubernetes Cluster Kubernetes allows us to make operations as simple as possible later on. Updates can be fully automated. In addition, Kubernetes allows us to ensure a secure @@ -92,7 +92,7 @@ future. We are constantly working on expanding our documentation. This installation method is currently not documented. If it is relevant, please feel free to contact us at set@deutschebahn.com or open an issue in this repository. -## Step 2: Validate the available resources +## Step 2: Validate the Available Resources The minimum required resources are 3 [Kubernetes CPU cores](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) @@ -104,7 +104,7 @@ Each session requires a minimum of 0.4 Kubernetes CPU cores and 1.6Gi of memory. A session can scale up until it reaches 2 Kubernetes CPU cores and 6Gi of memory. -## Step 3: Set up the required namespaces (optional) +## Step 3: Set up the Required Namespaces (Optional) The Collaboration Manager requires two different namespaces. For security and overview reasons, they are separated: @@ -150,7 +150,7 @@ Verify that `helm` is working by executing the command: helm version ``` -## Step 5: Clone the Github repository +## Step 5: Clone the Github Repository Navigate to a persistent location on your server, e.g. `/opt`. Then clone the Github repository by running: @@ -159,7 +159,7 @@ Github repository by running: git clone https://github.com/DSD-DBS/capella-collab-manager.git ``` -## Step 6: Configure the environment / Create the `values.yaml` +## Step 6: Configure the Environment / Create the `values.yaml` Copy the [`values.yaml`](https://github.com/DSD-DBS/capella-collab-manager/blob/main/helm/values.yaml) @@ -175,7 +175,7 @@ chmod 600 values.yaml Adjust all values according to your needs. -## Step 7: Install the application in the cluster +## Step 7: Install the Application in the Cluster Run the following commands in the root directory of the repository: @@ -188,7 +188,7 @@ helm upgrade --install \ ./helm ``` -## Step 8: Initialize the Guacamole database +## Step 8: Initialize the Guacamole Database The Guacamole database is not initialized automatically. Run the following command to initialize the PostgreSQL database: @@ -213,7 +213,7 @@ have to change it to a more secure password: works. 1. Update the key `guacamole.password` in the `values.yaml` and repeat step 7. -## Step 9: Check the application status +## Step 9: Check the Application Status Run `kubectl get pods` to see the status of all components. Once all containers are running, verify the installation state by running: @@ -230,7 +230,7 @@ It should return the following JSON: If a value is false, check the backend logs for more information. -## Step 10: Add TeamForCapella support +## Step 10: Add TeamForCapella Support !!! info "TeamForCapella server required" diff --git a/docs/docs/development/backend/authentication.md b/docs/docs/development/backend/authentication.md index 8970cb14d2..599d434d4c 100644 --- a/docs/docs/development/backend/authentication.md +++ b/docs/docs/development/backend/authentication.md @@ -3,12 +3,15 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -## Authentication via personal access token (requires a running frontend) +## Authentication via Personal Access Token (Requires a Running Frontend) Find more information about authentication with personal access tokens in the user documentation: [Authentication](../../user/tokens.md) -## Authentication without application frontend +As soon as you have a PAT (Personal Access Token) you can authenticate without +the application frontend. + +## Authentication without Application Frontend Request the `auth_url` diff --git a/docs/docs/development/backend/code-style.md b/docs/docs/development/backend/code-style.md index 1f509bcd27..4e8c99008c 100644 --- a/docs/docs/development/backend/code-style.md +++ b/docs/docs/development/backend/code-style.md @@ -100,7 +100,7 @@ Python code. The key differences are: `from .. import y as z` for one level above. For all other imports beyond this level, use the full path as described in 3. -### Naming conventions +### Naming Conventions - All SQLAlchemy models should have `Database` as a prefix, e.g., `DatabaseProject` or `DatabaseUser`. diff --git a/docs/docs/development/backend/database-migration.md b/docs/docs/development/backend/database-migration.md index 50f4d39693..2497dceb83 100644 --- a/docs/docs/development/backend/database-migration.md +++ b/docs/docs/development/backend/database-migration.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Create database migrations scripts +# Create Database Migration Scripts To create an upgrade script automatically (this will compare the current database state with the models): diff --git a/docs/docs/development/backend/exception.md b/docs/docs/development/backend/exception.md index c764a94557..2c2bf93331 100644 --- a/docs/docs/development/backend/exception.md +++ b/docs/docs/development/backend/exception.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Exception handling +# Exception Handling Various errors can occur in the backend, which must be made understandable to the end user and the developers diff --git a/docs/docs/development/backend/extensions.md b/docs/docs/development/backend/extensions.md index 363ab36120..52cab0ce0c 100644 --- a/docs/docs/development/backend/extensions.md +++ b/docs/docs/development/backend/extensions.md @@ -21,7 +21,7 @@ extension The different components are explained in the following section. -## Extension modules +## Extension Modules ### `__init__.py` diff --git a/docs/docs/development/docs.md b/docs/docs/development/docs.md new file mode 100644 index 0000000000..8e03af8e0a --- /dev/null +++ b/docs/docs/development/docs.md @@ -0,0 +1,23 @@ + + +# Documentation + +Write documentation if necessary so that developer, administrators and users +have an easily accessible way of learning about the collaboration manager. + +## Setup and Serve the Documentation + +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. + +## 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). +In addition personal names/ names of packages are written according to their +documentation. diff --git a/docs/docs/development/frontend/code-style.md b/docs/docs/development/frontend/code-style.md index fb71c03947..324a18337e 100644 --- a/docs/docs/development/frontend/code-style.md +++ b/docs/docs/development/frontend/code-style.md @@ -7,12 +7,12 @@ ### Crud Functions -#### Creating resource +#### Creating Resource For creating a resource one should use `create` as a prefix followed by the resource one wants to create (e.g., `createProject(...): Observable`) -#### Retriving resources +#### Retriving Resources In general, one should use `get` as prefix for a function that retrieves and returns resources. In case, one wants to get a list of alls resources use diff --git a/docs/docs/development/frontend/customize.md b/docs/docs/development/frontend/customize.md index e8fd91333c..1d8688e312 100644 --- a/docs/docs/development/frontend/customize.md +++ b/docs/docs/development/frontend/customize.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Customize the frontend +# Customize the Frontend You can customize the frontend by using a custom theme and a custom favicon: diff --git a/docs/docs/development/frontend/routes.md b/docs/docs/development/frontend/routes.md index 94f250f659..445723acca 100644 --- a/docs/docs/development/frontend/routes.md +++ b/docs/docs/development/frontend/routes.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Frontend routes +# Frontend Routes For consistency, we have a strict structure for our frontend route URIs. The structure is based on REST, but not completely the same due to the limitations of the unavailable request methods. diff --git a/docs/docs/development/frontend/testing.md b/docs/docs/development/frontend/testing.md index cc16859b61..5024622fa3 100644 --- a/docs/docs/development/frontend/testing.md +++ b/docs/docs/development/frontend/testing.md @@ -11,7 +11,7 @@ our team does not require frontend tests for every component or service. Please ensure that ".spec" files are only included if they have active tests. Before writing tests, consider the overhead and weigh it against the potential benefits. -## Unit & Integration testing +## Unit & Integration Testing ### Technologies @@ -19,14 +19,14 @@ Before writing tests, consider the overhead and weigh it against the potential b - [Karma] is used as test runner - We use [istanbul] to measure and visualize the code coverage -### Additional sources +### Additional Sources - [Official angular testing guide] - Recommended: [Detailed angular testing guide] ### General -#### Robust component tests +#### Robust Component Tests When testing components, we must query the elements needed for the test. To ensure that even if the element type or attributes changes, the element @@ -39,14 +39,14 @@ where the prefix usually describes the general contex (e.g., whether it is an input, button, textfield, etc.) and the following description specifies the usage of it (e.g., createProject). -#### Element helper functions +#### Element Helper Functions Usually testing components consists of querying elements, applying changes to them, triggering events on them, and then comparing the results with the expected results. To reduce repetition and increase readability, one should use existing helper functions or create new ones if none exist. -### Executing tests +### Executing Tests To execute the integration tests, one needs to run `make test`. However, in some cases it is not possible to correctly set the `CHROME_BIN` that is needed to generate @@ -68,13 +68,13 @@ and line coverage) are output to the console. To also see what exactly is covered and what is missing, one can open the `index.html` file in the `/frontend/test-results/istanbul-coverage` folder. -## End-to-End testing +## End-to-End Testing ### Technologies - We use [playwright] for E2E testing -### Test generation +### Test Generation Playwright supports the generation of E2E tests by interacting with the frontend and recording each action and input. This can be started @@ -86,7 +86,7 @@ one should only use the resulting test as a base and adjust it accordingly. For example, check selectors and adjust them to make them more robust, or add more expectations as needed. -### Executing tests +### Executing Tests To run the E2E tests, one must first make sure that a backend is running. If that is the case, one can run `npx playwright test` to start diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md index ae8a422907..ed418dc552 100644 --- a/docs/docs/development/index.md +++ b/docs/docs/development/index.md @@ -15,7 +15,7 @@ go ahead and to contribute code. In order to reduce the burden on our maintainers, please make sure that your code follows our style guidelines. -## Setup of a local Development Environment +## Setup of a Local Development Environment In addition to the [local k8s deployment](https://github.com/DSD-DBS/capella-collab-manager#running-locally-with-k3d), @@ -31,7 +31,7 @@ reloading of the frontend and backend. - `npm` package manager - [`Angular CLI`](https://angular.io/cli#installing-angular-cli) -### Backend configuration +### Backend Configuration The backend uses various configuration settings. You can find them in the `config` directory. Please copy the file `config_template.yaml` to @@ -43,7 +43,7 @@ application deployed, then no configuration values need to be adjusted. _Hint_: You can run `python -m capellacollab.config.diff` after each update to check if your config is up to date. -### Get started +### Getting Started To get started, run the following command in the root of the repository for the initial setup (only required once): @@ -67,7 +67,7 @@ If everything went well, the frontend and backend should be running now: - [Backend API documentation](http://localhost:8000/docs) - [Capella Collaboration Manager Documentation](http://localhost:8081) -## General notes +## General Notes ### REST APIs diff --git a/docs/docs/user/index.md b/docs/docs/user/index.md index 7873b003fd..f8114ea549 100644 --- a/docs/docs/user/index.md +++ b/docs/docs/user/index.md @@ -19,7 +19,7 @@ the tool. It also takes care of the housekeeping of the modeling projects themselves. And that's not all: We also offer project access management and since the site is completely responsive it is also usable on smartphones. -## Automations and model-derived products +## Automations and Model-derived Products Git is quite in the middle of the modeling lifecycle. We also use its automation means (CI/CD) to automate a number of housekeeping activities: @@ -99,7 +99,7 @@ There are 3 roles you can have in a project context: You may also [learn more about the roles model here](projects/roles.md). -## Next steps +## Next Steps If you like to start a new project and work on it via Collab Manager - please follow this guide: [project onboarding guideline](projects/create.md) to @@ -120,7 +120,7 @@ sections: - Getting started with a git-only project (not yet documented, contact your toolchain team for onboarding) -## Missing information / need support +## Missing Information / Need Support !!! warning "Important" diff --git a/docs/docs/user/projects/access.md b/docs/docs/user/projects/access.md index 3dfba0556c..92f7474258 100644 --- a/docs/docs/user/projects/access.md +++ b/docs/docs/user/projects/access.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# How do I get access to a project? +# How do I Get Access to a Project? Please ask a [project lead](roles.md) of the specific project for access. The project lead can add you as user to the project. After you've been added, you diff --git a/docs/docs/user/projects/add-user.md b/docs/docs/user/projects/add-user.md index 61f51b45df..61a3ebb23a 100644 --- a/docs/docs/user/projects/add-user.md +++ b/docs/docs/user/projects/add-user.md @@ -8,7 +8,7 @@ You need to have the Administrator or Project Lead role for a project to perform the following steps. -## Add user to project +## Add User to Project 1. Select your project in the project overview. 2. On the right side you should now see user management options: @@ -22,7 +22,7 @@ ![Add user](add-user/add-user.png) -## Modify role or permissions of user +## Modify Role or Permissions of User diff --git a/docs/docs/user/projects/create.md b/docs/docs/user/projects/create.md index b40411f2d1..34aa6e8821 100644 --- a/docs/docs/user/projects/create.md +++ b/docs/docs/user/projects/create.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Create a _Collaboration Manager_ project +# Create a _Collaboration Manager_ Project In the Collaboration Manager, you can follow a guided process to create projects. Any user can create a project. After creation, you get the role @@ -12,14 +12,14 @@ to the _Projects_ tab of the navigation bar, and click on _Add new project_. Please follow the steps: -## Step 1: General information +## Step 1: General Information Please enter a unique name to identify the project. The project name can not be changed! Additionally, you may want to add a description. ![Step 1: General information](create/step-1.png) -## Step 2: Add team members +## Step 2: Add Team Members This page allows to manage the project user. By default, you are project lead of the project. If you don't want to add an additional user, you can skip this @@ -27,7 +27,7 @@ step. Users can be added later at any time. ![Step 2: Team members](create/step-2.png) -## Step 3: Add models +## Step 3: Add Models Please follow the model creation instructions to setup a model: [Create a model](models/create.md) diff --git a/docs/docs/user/projects/models/backups/remove.md b/docs/docs/user/projects/models/backups/remove.md index 24c6865606..46f6573a33 100644 --- a/docs/docs/user/projects/models/backups/remove.md +++ b/docs/docs/user/projects/models/backups/remove.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Remove a (nightly) backup +# Remove a (Nightly) Backup !!! warning diff --git a/docs/docs/user/projects/models/backups/setup.md b/docs/docs/user/projects/models/backups/setup.md index ff8fe2e3bd..1de7061966 100644 --- a/docs/docs/user/projects/models/backups/setup.md +++ b/docs/docs/user/projects/models/backups/setup.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Set up a backup for a TeamForCapella model +# Set up a Backup for a TeamForCapella Model !!! warning diff --git a/docs/docs/user/projects/models/complexity_badge.md b/docs/docs/user/projects/models/complexity_badge.md index 8b41e6a289..3b52c05c4a 100644 --- a/docs/docs/user/projects/models/complexity_badge.md +++ b/docs/docs/user/projects/models/complexity_badge.md @@ -3,9 +3,9 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Model complexity badge integration +# Model Complexity Badge Integration -## Set up the complexity badge +## Set up the Complexity Badge !!! warning @@ -37,7 +37,7 @@ to add the complexity badge pipeline to the linked repository. -## View the model complexity badge +## View the Model Complexity Badge The model complexity badge is visible in the model overview in the project details: diff --git a/docs/docs/user/projects/models/create.md b/docs/docs/user/projects/models/create.md index a88aeddd2c..e229513238 100644 --- a/docs/docs/user/projects/models/create.md +++ b/docs/docs/user/projects/models/create.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Create a _Collaboration Manager_ model +# Create a _Collaboration Manager_ Model We offer a guided process to create models in a project. To create a model, you have to be at least [project lead](../../projects/roles.md). If you're coming @@ -15,12 +15,12 @@ The creation can be interrupted at any step, however an unfinished model will lack some essential features, so it’s recommended to go through the whole process. -## Step 1: Create model +## Step 1: Create Model This page allows to set a project name, description, and a tool. The name and tool are required. The tool can be changed after the model creation. -## Step 2: Choose primary source +## Step 2: Choose Primary Source On this page, you can select the type of source. Right now, we offer the following options: @@ -39,13 +39,13 @@ following options: abort the process here and continue with the help of an administrator later on. -## Step 3: Add source +## Step 3: Add Source If you chose option 1 or 2 in the last step, please read the `Link existing Git repository` part of this step. If you chose option 3 or 4, you can should read the `Link existing T4C repository` part. -### Step 3.1 Link existing Git repository +### Step 3.1 Link Existing Git Repository It is important for this step to have an existing Git repository which is reachable from inside your environment. @@ -88,7 +88,7 @@ You have to enter the following information: -### Step 3.2 Link existing T4C repository +### Step 3.2 Link Existing T4C Repository !!! warning @@ -99,7 +99,7 @@ the TeamForCapella instance and the TeamForCapella repository. With `project`, you can specify the name of the model in Capella. We recommend using the same name for the repository and project. -## Step 4: Choose initialisation +## Step 4: Choose Initialisation Please choose `Create empty model`. This has no effect on the existing TeamForCapella content. More options will follow in the future. diff --git a/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md b/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md index 2dc8ead1ff..70ea932825 100644 --- a/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md +++ b/docs/docs/user/projects/models/diagrams/setup_diagram_cache.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Set up the diagram cache integration +# Set up the Diagram Cache Integration !!! warning diff --git a/docs/docs/user/projects/models/diagrams/view_diagram_cache.md b/docs/docs/user/projects/models/diagrams/view_diagram_cache.md index d355469a0f..39c1214021 100644 --- a/docs/docs/user/projects/models/diagrams/view_diagram_cache.md +++ b/docs/docs/user/projects/models/diagrams/view_diagram_cache.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# View diagrams via the diagram cache integration +# View Diagrams via the Diagram Cache Integration 1. Navigate to your project in the project overview. 2. In the model overview, select the diagrams button: diff --git a/docs/docs/user/projects/models/metadata.md b/docs/docs/user/projects/models/metadata.md index cc7ff5c1c0..aae3f4c656 100644 --- a/docs/docs/user/projects/models/metadata.md +++ b/docs/docs/user/projects/models/metadata.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Update model metadata (version and nature) +# Update Model Metadata (Version and Nature) 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/projects/models/sources/t4c.md b/docs/docs/user/projects/models/sources/t4c.md index ba355a8233..b785324fd1 100644 --- a/docs/docs/user/projects/models/sources/t4c.md +++ b/docs/docs/user/projects/models/sources/t4c.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Manage the TeamForCapella project integration +# Manage the TeamForCapella Project Integration !!! warning @@ -13,7 +13,7 @@ For all actions, you need to navigate to `Projects`, and select the model sources button for the model.
![Model sources](./open-modelsources.png) -## Link a TeamForCapella repository to a project model +## Link a TeamForCapella Repository to a Project Model 1. Click on `Use existing repository` in the `T4C Models` section. 1. Select the TeamForCapella instance, the repository and enter a project name. @@ -27,7 +27,7 @@ sources button for the model.
![Model sources](./open-modelsources.png) will get access to the repository during the next session start. The session token will not be updated for existing/open sessions. -## Unlink a TeamForCapella repository from a project model +## Unlink a TeamForCapella Repository from a Project Model 1. Select the TeamForCapella reference/integration from the list. 1. Click on `Unlink` and confirm. diff --git a/docs/docs/user/projects/models/update.md b/docs/docs/user/projects/models/update.md index 2752a3c14c..7631fa0cc2 100644 --- a/docs/docs/user/projects/models/update.md +++ b/docs/docs/user/projects/models/update.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Update a model to a newer version +# Update a Model to a Newer Version !!! warning diff --git a/docs/docs/user/sessions/files/files.md b/docs/docs/user/sessions/files/files.md index bf416c69e9..df21bce00c 100644 --- a/docs/docs/user/sessions/files/files.md +++ b/docs/docs/user/sessions/files/files.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Browse, upload and download files +# Browse, Upload and Download Files diff --git a/docs/docs/user/sessions/flows/t4c.md b/docs/docs/user/sessions/flows/t4c.md index a4bbbe9577..fdb8b493b9 100644 --- a/docs/docs/user/sessions/flows/t4c.md +++ b/docs/docs/user/sessions/flows/t4c.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Connect to a TeamForCapella repository +# Connect to a TeamForCapella Repository !!! Info diff --git a/docs/docs/user/sessions/request.md b/docs/docs/user/sessions/request.md index 52ce951171..aad0962049 100644 --- a/docs/docs/user/sessions/request.md +++ b/docs/docs/user/sessions/request.md @@ -21,7 +21,7 @@ Please follow these steps to request a session: 1. Wait for your read-only session to become ready and open it with the `Connect` button. -## Automatic session termination +## Automatic Session Termination When your session is inactive for a long time (default 90 minutes), your session is terminated. A session is considered inactive when there is no user diff --git a/docs/docs/user/sessions/screenshot/screenshots.md b/docs/docs/user/sessions/screenshot/screenshots.md index 6e90feb232..d5322ad481 100644 --- a/docs/docs/user/sessions/screenshot/screenshots.md +++ b/docs/docs/user/sessions/screenshot/screenshots.md @@ -8,7 +8,7 @@ Some screenshot tools use the clipboard and keyboard shortcuts. This sometimes does not work in the Capella Collaboration Manager. -## Technical background +## Technical Background Some keyboard combinations are directly mapped into the containers where Capella is running. This allows to use these keyboard combinations for actions @@ -22,7 +22,7 @@ the clipboard of the host system. ## Solution -### Snipping tool +### Snipping Tool The Snipping tool (Windows) should just work. diff --git a/docs/docs/user/sessions/types.md b/docs/docs/user/sessions/types.md index b72d5aa649..04f730b166 100644 --- a/docs/docs/user/sessions/types.md +++ b/docs/docs/user/sessions/types.md @@ -26,7 +26,7 @@ the T4C connection dialog. Only work stored in the `/workspace` folder (default workspace folder) will be persistent. -### Persistent Jupyter notebooks +### Persistent Jupyter Notebooks Jupyter notebooks allow you to programmatically explore (capella) models. You'll use the same shared workspace as with persistent Capella/Papyrus diff --git a/docs/docs/user/sessions/types/persistent.md b/docs/docs/user/sessions/types/persistent.md index 6e9d0e0ea8..fcd3629f79 100644 --- a/docs/docs/user/sessions/types/persistent.md +++ b/docs/docs/user/sessions/types/persistent.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Getting started with a persistent session +# Getting Started with a Persistent Session diff --git a/docs/docs/user/sessions/types/read-only.md b/docs/docs/user/sessions/types/read-only.md index b51f6842ab..7bfccf7d9c 100644 --- a/docs/docs/user/sessions/types/read-only.md +++ b/docs/docs/user/sessions/types/read-only.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Getting started with read-only project access +# Getting Started with Read-only Project Access If you have read-only project access, or you simply want to check the model without risk of editing, you may start a read-only session. diff --git a/docs/docs/user/settings/model-sources/git.md b/docs/docs/user/settings/model-sources/git.md index 887e11398b..f78054d06d 100644 --- a/docs/docs/user/settings/model-sources/git.md +++ b/docs/docs/user/settings/model-sources/git.md @@ -3,18 +3,18 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Manage Git instances +# Manage Git Instances With Git instances, administrators can restrict the location of Git repositories. -## No Git instance defined +## No Git Instance Defined When you don't want to define Git instances, users can use any location for their repositories. Some features, which require a specific instance, e.g., Gitlab, are not available. -## Define a Git instance +## Define a Git Instance 1. Please navigate to `Profile` > `Settings` 1. Select `Git` below `Model sources` @@ -37,7 +37,7 @@ Gitlab, are not available. New repositories have to match at least one instance. Otherwise, they can not be added as model source to models. -## Matching between models and instances +## Matching between Models and Instances Models are matched with instances with a longest prefix match of the URL. diff --git a/docs/docs/user/settings/model-sources/t4c.md b/docs/docs/user/settings/model-sources/t4c.md index c75d462f25..e34ec66393 100644 --- a/docs/docs/user/settings/model-sources/t4c.md +++ b/docs/docs/user/settings/model-sources/t4c.md @@ -3,9 +3,9 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Manage T4C instances +# Manage T4C Instances -## Define a T4C instance +## Define a T4C Instance 1. Please navigate to `Profile` > `Settings` 1. Select `T4C` bewlow `Model sources` @@ -25,7 +25,7 @@ with the REST API 1. **Password**: Password corresponding to username -## Archive a T4C instance +## Archive a T4C Instance 1. Please navigate to `Profile` > `Settings` 1. Select `T4C` bewlow `Model sources` diff --git a/docs/docs/user/settings/monitoring.md b/docs/docs/user/settings/monitoring.md index bd5b835d12..e71917e0a3 100644 --- a/docs/docs/user/settings/monitoring.md +++ b/docs/docs/user/settings/monitoring.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Pipeline and model modifier monitoring +# Pipeline and Model Modifier Monitoring !!! info diff --git a/docs/docs/user/settings/tools/index.md b/docs/docs/user/settings/tools/index.md index 9f3c832f03..15d045c48f 100644 --- a/docs/docs/user/settings/tools/index.md +++ b/docs/docs/user/settings/tools/index.md @@ -3,13 +3,13 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Tools management +# Tools Management Starting with `v2.0.0`, there is a support for general tools. This allows the use of many different `Eclipse` based tools (and even more tools if they are dockerized). -## Managing tools +## Managing Tools !!! warning diff --git a/docs/docs/user/settings/tools/pure_variants.md b/docs/docs/user/settings/tools/pure_variants.md index a8abf96467..d94009d87c 100644 --- a/docs/docs/user/settings/tools/pure_variants.md +++ b/docs/docs/user/settings/tools/pure_variants.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# pure::variants integration +# `pure::variants` Integration !!! info @@ -13,20 +13,20 @@ - Use the pure::variants connector for Capella in a browser - Manage licenses as a self-service on a project level -## Setup of `pure::variants` integration +## Setup of `pure::variants` Integration !!! warning The setup can only be performed by administrators. If you want to get access as user, please refer to [Get access to the `pure::variants` license as user](#get-access-to-the-purevariants-license-as-user) -### Set license server URL and upload `license.lic` +### Set License Server URL and Upload `license.lic` 1. Navigate to `Profile` > `Settings` 1. Select `pure::variants` in the `Integrations` section. 1. Modify the floating license server URL and confirm with `Update`. 1. Upload the `license.lic` license file. -### Add the `pure::variants` tool to your instance +### Add the `pure::variants` Tool to your Instance 1. Navigate to `Profile` > `Settings` 1. Select `Tools` in the `Core functionality` section. @@ -46,7 +46,7 @@ 1. Add tool natures if applicable. If not tool nature is applicable, use a placeholder. -### Whitelist a model for `pure::variants` +### Whitelist a Model for `pure::variants` 1. Open the project perspective of a selected project. 1. If you don't have model with the `pure::variants` tool yet, @@ -58,7 +58,7 @@ 1. All members of the project should now have access to the `pure::variants` license server. -## Get access to the `pure::variants` license as user +## Get Access to the `pure::variants` License as User You have to get access to a project with at least one `pure::variants` whitelisted model. More information: diff --git a/docs/docs/user/tools/capella/introduction.md b/docs/docs/user/tools/capella/introduction.md index 0ac99a4909..a2dd51c621 100644 --- a/docs/docs/user/tools/capella/introduction.md +++ b/docs/docs/user/tools/capella/introduction.md @@ -24,7 +24,7 @@ You may find more Capella - related videos on the official channel: Also you can try out this [Capella Tutorial](https://esd.sutd.edu.sg/40014-capella-tutorial/index.html) -## More advanced topics +## More Advanced Topics Methods for Modeling System of Systems with Capella: @@ -33,7 +33,7 @@ Methods for Modeling System of Systems with Capella: If you'd like to learn how Capella works you may want to read through our [guide for meta-model exploration](https://dsd-dbs.github.io/py-capellambse/start/how-to-explore-capella-mm.html) -## Deriving model-based products +## Deriving Model-based Products You may prototype-derived products using Python (Jupyter) and [py-capellambse](https://github.com/DSD-DBS/py-capellambse). It contains a few diff --git a/docs/docs/user/tools/capella/t4c-git-compare.md b/docs/docs/user/tools/capella/t4c-git-compare.md index 35e0faa485..8b64dde526 100644 --- a/docs/docs/user/tools/capella/t4c-git-compare.md +++ b/docs/docs/user/tools/capella/t4c-git-compare.md @@ -3,9 +3,9 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Ways of co-working on a Capella project +# Ways of Co-working on a Capella Project -## Quick comparision +## Quick Comparision @@ -85,7 +85,7 @@ practice this proves to be too time-consuming, as many changes become confusing very quickly. -## Some general words +## Some General Words 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 9fc2e86298..64b25d24bf 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 @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Export a Capella model from your persistent workspace to a TeamForCapella server +# Export a Capella Model from your Persistent Workspace to a TeamForCapella Server !!! warning 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 de272b128f..9e9c3d043d 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 @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# Import a Capella model from a TeamForCapella server into your persistent workspace +# Import a Capella Model from a TeamForCapella Server into your Persistent Workspace !!! warning diff --git a/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md b/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md index 6b34dbb7fd..06c9282880 100644 --- a/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md +++ b/docs/docs/user/tools/capella/teamforcapella/project-management/project-management.md @@ -10,7 +10,7 @@ cover the management of T4C repositories. For the management of T4C repositories, refer to the [TeamForCapella repository management](../repository-management.md) guide. -## Create a new TeamForCapella project +## 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. @@ -18,7 +18,7 @@ repositories, refer to the T4C repository. For more information, refer to the [TeamForCapella project export](../export/export-to-t4c.md) guide. -## Delete a TeamForCapella project +## Delete a TeamForCapella Project !!! warning diff --git a/docs/docs/user/tools/capella/teamforcapella/repository-management.md b/docs/docs/user/tools/capella/teamforcapella/repository-management.md index 4cebe49ccd..de3ffd20fa 100644 --- a/docs/docs/user/tools/capella/teamforcapella/repository-management.md +++ b/docs/docs/user/tools/capella/teamforcapella/repository-management.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# TeamForCapella repository management +# TeamForCapella Repository Management !!! info @@ -14,20 +14,20 @@ For all actions, you have to navigate to `Profile` > `Settings` > 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 +## Add a new TeamForCapella Repository 1. Enter the name of the repository in the `Repository name` field. 1. Click on `Add T4C repository` 1. The status should be `INITIAL`. Please wait until the status changes to `ONLINE` -## Start/Stop a TeamForCapella repository +## Start/Stop a TeamForCapella Repository 1. Select the repository from the list 1. Click the `Start repository` or `Stop repository` button on the bottom right. -## Remove a TeamForCapella repository +## Remove a TeamForCapella Repository !!! danger diff --git a/docs/docs/user/tools/capella/teamforcapella/update.md b/docs/docs/user/tools/capella/teamforcapella/update.md index 80288f30c7..396a236d69 100644 --- a/docs/docs/user/tools/capella/teamforcapella/update.md +++ b/docs/docs/user/tools/capella/teamforcapella/update.md @@ -3,7 +3,7 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -# How to update a Capella model to a higher version (in TeamForCapella) +# How to Update a Capella Model to a Higher Version (in TeamForCapella) !!! warning diff --git a/docs/docs/user/tools/capella/working-with-git.md b/docs/docs/user/tools/capella/working-with-git.md index c58e906940..402e76132a 100644 --- a/docs/docs/user/tools/capella/working-with-git.md +++ b/docs/docs/user/tools/capella/working-with-git.md @@ -59,7 +59,7 @@ 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 Project" and then open the project again. -## Prepare to Commit - Stage changes +## Prepare to Commit - Stage Changes In Git staged changes are saved changes that we mark to use in our next commit. @@ -234,7 +234,7 @@ Make sure to resolve all conflicts before commiting! After merging reopen the model and look especially into layouting as capella might be a bit opportunistic in merging layouts. -### Merging if Merge Tool is not possible +### Merging if Merge Tool is not Possible If merging with the merge tool is not possible you have to open the reset view. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 85c6317c01..05857ab84a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -98,6 +98,7 @@ nav: - Customization: development/frontend/customize.md - Kubernetes: - Meassure resource usage: development/k8s/resources.md + - Documentation: development/docs.md - Release Notes: release-notes.md repo_url: https://github.com/DSD-DBS/capella-collab-manager