From 83586474ce526794973fe43ad76461f6364faa62 Mon Sep 17 00:00:00 2001 From: Paula-Kli Date: Mon, 27 Nov 2023 11:13:40 +0100 Subject: [PATCH] docs: Fix documentation according to user feedback Remove video for jupyter notebook introduction. Move settings documentation from user to administrator documentation. Some smaller adjustments. --- .../settings/model-sources/git.md | 0 .../settings/model-sources/t4c.md | 0 .../{user => admin}/settings/monitoring.md | 6 ++-- .../{user => admin}/settings/tools/index.md | 4 --- .../settings/tools/model_restrictions.png | Bin .../tools/model_restrictions.png.license | 0 .../settings/tools/model_restrictions_pv.png | Bin .../tools/model_restrictions_pv.png.license | 0 .../settings/tools/pure_variants.md | 2 +- docs/docs/user/projects/models/create.md | 12 +++++-- docs/docs/user/projects/models/metadata.md | 4 +++ docs/docs/user/projects/models/update.md | 24 -------------- .../user/sessions/jupyter/collaboration.md | 8 ----- .../jupyter/jupyter-collaboration.mp4 | 3 -- docs/docs/user/tools/capella/introduction.md | 2 +- docs/docs/user/tools/capella/update.md | 30 ++++++++++++++++++ docs/mkdocs.yml | 22 ++++++------- 17 files changed, 58 insertions(+), 59 deletions(-) rename docs/docs/{user => admin}/settings/model-sources/git.md (100%) rename docs/docs/{user => admin}/settings/model-sources/t4c.md (100%) rename docs/docs/{user => admin}/settings/monitoring.md (76%) rename docs/docs/{user => admin}/settings/tools/index.md (87%) rename docs/docs/{user => admin}/settings/tools/model_restrictions.png (100%) rename docs/docs/{user => admin}/settings/tools/model_restrictions.png.license (100%) rename docs/docs/{user => admin}/settings/tools/model_restrictions_pv.png (100%) rename docs/docs/{user => admin}/settings/tools/model_restrictions_pv.png.license (100%) rename docs/docs/{user => admin}/settings/tools/pure_variants.md (92%) delete mode 100644 docs/docs/user/projects/models/update.md delete mode 100644 docs/docs/user/sessions/jupyter/jupyter-collaboration.mp4 create mode 100644 docs/docs/user/tools/capella/update.md diff --git a/docs/docs/user/settings/model-sources/git.md b/docs/docs/admin/settings/model-sources/git.md similarity index 100% rename from docs/docs/user/settings/model-sources/git.md rename to docs/docs/admin/settings/model-sources/git.md diff --git a/docs/docs/user/settings/model-sources/t4c.md b/docs/docs/admin/settings/model-sources/t4c.md similarity index 100% rename from docs/docs/user/settings/model-sources/t4c.md rename to docs/docs/admin/settings/model-sources/t4c.md diff --git a/docs/docs/user/settings/monitoring.md b/docs/docs/admin/settings/monitoring.md similarity index 76% rename from docs/docs/user/settings/monitoring.md rename to docs/docs/admin/settings/monitoring.md index d60d1d8124..1be7b6d900 100644 --- a/docs/docs/user/settings/monitoring.md +++ b/docs/docs/admin/settings/monitoring.md @@ -5,9 +5,7 @@ # Pipeline and Model Modifier Monitoring - -!!! info - Only administrators can see the monitoring dashboard. - 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` diff --git a/docs/docs/user/settings/tools/index.md b/docs/docs/admin/settings/tools/index.md similarity index 87% rename from docs/docs/user/settings/tools/index.md rename to docs/docs/admin/settings/tools/index.md index e747844a9b..d771c96fef 100644 --- a/docs/docs/user/settings/tools/index.md +++ b/docs/docs/admin/settings/tools/index.md @@ -11,10 +11,6 @@ dockerized). ## Managing Tools - -!!! warning - To manage tools, you have to be administrator. - The tool management page can be found at `Profile` > `Settings` > `Core` > `Tools`. It support the following: diff --git a/docs/docs/user/settings/tools/model_restrictions.png b/docs/docs/admin/settings/tools/model_restrictions.png similarity index 100% rename from docs/docs/user/settings/tools/model_restrictions.png rename to docs/docs/admin/settings/tools/model_restrictions.png diff --git a/docs/docs/user/settings/tools/model_restrictions.png.license b/docs/docs/admin/settings/tools/model_restrictions.png.license similarity index 100% rename from docs/docs/user/settings/tools/model_restrictions.png.license rename to docs/docs/admin/settings/tools/model_restrictions.png.license diff --git a/docs/docs/user/settings/tools/model_restrictions_pv.png b/docs/docs/admin/settings/tools/model_restrictions_pv.png similarity index 100% rename from docs/docs/user/settings/tools/model_restrictions_pv.png rename to docs/docs/admin/settings/tools/model_restrictions_pv.png diff --git a/docs/docs/user/settings/tools/model_restrictions_pv.png.license b/docs/docs/admin/settings/tools/model_restrictions_pv.png.license similarity index 100% rename from docs/docs/user/settings/tools/model_restrictions_pv.png.license rename to docs/docs/admin/settings/tools/model_restrictions_pv.png.license diff --git a/docs/docs/user/settings/tools/pure_variants.md b/docs/docs/admin/settings/tools/pure_variants.md similarity index 92% rename from docs/docs/user/settings/tools/pure_variants.md rename to docs/docs/admin/settings/tools/pure_variants.md index 5518e8a9d3..99b8d23a11 100644 --- a/docs/docs/user/settings/tools/pure_variants.md +++ b/docs/docs/admin/settings/tools/pure_variants.md @@ -17,7 +17,7 @@ !!! 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) + The setup can only be performed by administrators. If a user wants to get access, 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` diff --git a/docs/docs/user/projects/models/create.md b/docs/docs/user/projects/models/create.md index e78b8819f1..d2e6909cc8 100644 --- a/docs/docs/user/projects/models/create.md +++ b/docs/docs/user/projects/models/create.md @@ -101,6 +101,12 @@ name for the repository and project. ## Step 4: Metadata -This is an important step. Here, you can select the version and the model -nature of your tool. If you don't select any version, the functionality will be -restricted. You will not be able to setup backups or create read-only sessions. +This is an important step. + +Here, you can select the version and the model nature of your tool. If you +don't select any version, the functionality will be restricted. You will not be +able to setup backups or create read-only sessions. + +If suitable for your project, select one of the latest versions of Capella. +Older versions may be removed in the future. Make sure your model is up to date +and in case you update it in time. diff --git a/docs/docs/user/projects/models/metadata.md b/docs/docs/user/projects/models/metadata.md index b2d663e891..49db13288a 100644 --- a/docs/docs/user/projects/models/metadata.md +++ b/docs/docs/user/projects/models/metadata.md @@ -5,6 +5,10 @@ # Update Model Metadata (Version and Nature) + +!!! 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! + 1. Navigate to `Projects` and select the project. 1. In the model overview and select the :material-cog: icon on model you'd like to modify. diff --git a/docs/docs/user/projects/models/update.md b/docs/docs/user/projects/models/update.md deleted file mode 100644 index 261c4ee2a3..0000000000 --- a/docs/docs/user/projects/models/update.md +++ /dev/null @@ -1,24 +0,0 @@ - - -# Update a Model to a Newer Version - - -!!! warning - Create backups (e.g. in a Git repository) before you start the update process. - A downgrade of models may not be possible (depends on the tool). - - -!!! info - If you want to update a Capella model, please follow the Capella specific instructions instead: - [Update a TeamForCapella based Capella model](../../tools/capella/teamforcapella/update.md) - -1. Open a new persistent session with the old version of your tool. -1. Load the model with the old version into your persistent workspace. -1. Close the session. -1. Remove the automatic backup option in the Capella Collaboration Manager, - we'll rewire it at the end of this tutorial. -1. Create a new session with the new Capella version. -1. Migrate the model in your local workspace. diff --git a/docs/docs/user/sessions/jupyter/collaboration.md b/docs/docs/user/sessions/jupyter/collaboration.md index c12d92efc8..c75b921dd9 100644 --- a/docs/docs/user/sessions/jupyter/collaboration.md +++ b/docs/docs/user/sessions/jupyter/collaboration.md @@ -28,14 +28,6 @@ connect to your sessions, follow these steps: 6. **Share the Link**: Distribute the link to all users who should have access. They will be able to open your notebooks and concurrently edit them. -#### Instructional Video - -Here's a video that visually guides you through these steps: - - - ## Collaboration on Project Level If you need a shared workspace for notebooks at the project level, you can diff --git a/docs/docs/user/sessions/jupyter/jupyter-collaboration.mp4 b/docs/docs/user/sessions/jupyter/jupyter-collaboration.mp4 deleted file mode 100644 index efc189ab98..0000000000 --- a/docs/docs/user/sessions/jupyter/jupyter-collaboration.mp4 +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:c1eb20daddfb070885869dfff861f3a4fcd34fc8cdc196e8b3fdbd1cd9a5c7f9 -size 2285837 diff --git a/docs/docs/user/tools/capella/introduction.md b/docs/docs/user/tools/capella/introduction.md index 8974a05a18..1bb5b28ebe 100644 --- a/docs/docs/user/tools/capella/introduction.md +++ b/docs/docs/user/tools/capella/introduction.md @@ -31,7 +31,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) +[guide for meta-model exploration](https://dsd-dbs.github.io/py-capellambse/development/how-to-explore-capella-mm.html) ## Deriving Model-based Products diff --git a/docs/docs/user/tools/capella/update.md b/docs/docs/user/tools/capella/update.md new file mode 100644 index 0000000000..19364e0f4b --- /dev/null +++ b/docs/docs/user/tools/capella/update.md @@ -0,0 +1,30 @@ + + +# Update a Capella Model to a Newer Version + + +!!! warning + Create backups (e.g. in a Git repository) before you start the update process. + A downgrade of Capella models is not possible. + + +!!! 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) + +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](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 required. + ![Disable backup option](../../tools/capella/teamforcapella/backup-migration.png) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a593ec6831..1ca183e13f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -22,7 +22,6 @@ nav: - Roles: user/projects/roles.md - Models: - Create a Model: user/projects/models/create.md - - Update a Model to a Newer Version: user/projects/models/update.md - Update Model Metadata: user/projects/models/metadata.md - Model Sources: - TeamForCapella: user/projects/models/sources/t4c.md @@ -50,19 +49,10 @@ nav: - Troubleshooting: user/sessions/troubleshooting.md - Jupyter: - Collaboration: user/sessions/jupyter/collaboration.md - - Settings: - - Monitoring: user/settings/monitoring.md - - Tools: - - General: user/settings/tools/index.md - - pure::variants: user/settings/tools/pure_variants.md - - Model sources: - - Git: user/settings/model-sources/git.md - - T4C: user/settings/model-sources/t4c.md - - Alerts: - - Create an Alert: user/alerts/create.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 @@ -78,6 +68,16 @@ nav: - 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 - CI templates: - Gitlab CI/CD: - Image builder: admin/ci-templates/gitlab/image-builder.md