docs: Update documentation

DSD-DBS · Jan 3, 2024 · 29d9ca0 · 29d9ca0
1 parent 34979ad
commit 29d9ca0
Show file tree

Hide file tree

Showing 4 changed files with 125 additions and 65 deletions.
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -2,40 +2,51 @@
    Copyright DB InfraGO AG and contributors
    SPDX-License-Identifier: Apache-2.0
 
-.. _config:
+.. _capella2polarion-config:
 
 YAML
 ====
-To control the migration of model elements, you can use the following YAML
-file. In this file, you can specify the layer and class type for matching
-objects. If an item is a dictionary, it means there are work item links to be
-migrated. Make sure to use the attribute names on the capellambse object
-correctly.
+To control the migration of model elements, the following YAML file serves as a
+configuration for the capella2polarion service. In this file, you can specify
+the layer, the type in Polarion, the class type for matching objects in
+capellambse, the serializer to use. If an item is a dictionary, it means there
+are work item links to be migrated. Make sure to use the attribute names on the
+capellambse object correctly.
 
 .. literalinclude:: ../../tests/data/model_elements/config.yaml
    :language: yaml
    :lines: 4-
 
 The first section is a general configuration where you can set links to be
-migrated for all class types. For example, ``parent`` and ``description_reference``
-are links that will be applied to all specified class types. Since ``Class`` is a
-common class type that exists in all layers, links specific to ``Class`` can be
-specified here to avoid duplication.
+migrated for all class types. For example, ``parent`` and
+``description_reference`` are links that will be applied to all specified class
+types. Since ``Class`` is a common type that exists in all layers, links
+specific to ``Class`` can be specified here to avoid duplication within the
+file.
+
+.. _polarion-config:
 
 Polarion
 ========
 In general, if an attribute is not configured, it will still be accepted and
-created via the Rest API. However, to be able to make ``GET`` requests, you
-need to configure your Polarion project correctly. The matching of diagrams and
-model elements is done using the ``uuid_capella`` attribute, which needs to be
-declared in the ``Custom Fields`` section. Simply choose ``All Types`` for this
-attribute.
+created via the Rest API but it will be handled as a plain string attribute.
+However, to be able to make ``GET`` requests, you need to configure your
+Polarion project correctly. For that there is the `Polarion DBS Project
+Template`_ which includes icon, custom field and enumeration configuration for
+a pleasant capella2polarion synchronization.
+
+.. _Polarion DBS Project Template: https://github.com/DSD-DBS/capella-polarion-template#polarion-dbs-project-template
+
+In the following are some requirements for the configuration if you don't want
+to use the Project Template:
+
+The matching of diagrams and model elements is done using the ``uuid_capella``
+attribute, which needs to be declared in the ``Custom Fields`` section. Simply
+choose ``All Types`` for this attribute.
 
 To have icons for your model elements, you need to declare the work item type
-in the ``workitem-type-enum.xml`` file in the Polarion administration panel.
-This file is an enumeration file where the work item type IDs should follow the
-camel case pattern (e.g., ``operationalCapability`` for
-``OperationalCapability``).
+in the ``workitem-type-enum.xml`` file in the Polarion administration panel and
+upload a 16x16 picture file.
 
 To generate clickable linked work items, you need to configure the link role
 enumerations in the ``workitem-link-role-enum.xml`` file. Here, the ID should

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,27 +7,38 @@ capella2polarion
 
 A tool to migrate Capella content to a Polarion project as work items.
 
-Diagrams
---------
-Migrate diagrams from a diagram cache (pipeline artifact from a capella diagram
-cache) job run to Polarion as work items. The whole folder with the
-``index.json`` and the SVGs is needed.
-
-Model-Elements
---------------
+Synchronization of Model-Elements
+---------------------------------
+
 Migrate any model element from a ``capellambse.MelodyModel`` to Polarion as a
-work item. With appropriate :ref:`configuration <config>` on Polarion and an
-according config YAML file, any attribute on the capellambse object can be
-migrated as a work item link if (and only if) the target object exists as a
-work item already. In order to generate diagram references, make sure to
-execute the model-elements migration after the diagram migration.
+work item. Diagrams are taken from a diagram cache (pipeline artifact from a
+`capella diagram cache`_) job run to Polarion as work items. The whole folder
+with the ``index.json`` and the SVGs is needed for the diagram synchronization.
+The SVG and a PNG of it are attached to the respective work item.
+
+With appropriate :ref:`configuration <capella2polarion-config>` on Polarion
+and an according :ref:`config YAML file <polarion-config>` for
+capella2polarion any model element can be migrated from a Capella model to a
+Polarion project. Attributes are migrated as links and text from requirements
+and link groups are synchronized as custom fields.
+
+The synchronization works by comparing the checksum of work items. If they
+differ the old will be patched by the new one.
+
+.. _capella diagram cache: https://github.com/DSD-DBS/capella-dockerimages/blob/main/ci-templates/gitlab/diagram-cache.yml
 
 .. toctree::
    :maxdepth: 2
    :caption: Configuration:
 
    configuration
 
+.. toctree::
+   :maxdepth: 2
+   :caption: CI/CD Template:
+
+   pipeline templates/gitlab
+
 .. toctree::
    :maxdepth: 3
    :caption: API reference

diff --git a/docs/source/pipeline templates/gitlab.rst b/docs/source/pipeline templates/gitlab.rst
@@ -0,0 +1,38 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+GitLab CI/CD pipeline Template
+------------------------------
+
+The capella2polarion library can be used in a CI/CD pipeline. For that the
+following template can be used inside the `.gitlab-ci.yml` file:
+
+.. literalinclude:: ../../../ci-templates/gitlab/synchronise_elements.yml
+   :language: yaml
+   :lines: 4-
+
+A `.gitlab-ci.yml` with a capella2polarion synchronization job could look like
+this:
+
+.. code:: yaml
+
+    include:
+        - remote: https://raw.githubusercontent.com/DSD-DBS/capella-dockerimages/${CAPELLA_DOCKER_IMAGES_REVISION}/ci-templates/gitlab/diagram-cache.yml
+        - remote: https://raw.githubusercontent.com/DSD-DBS/capella-polarion/ci-templates/gitlab/synchronise_elements.yml
+
+    default:
+        tags:
+            - docker
+
+    workflow: # Control job triggering
+        rules:
+            - if: $CI_COMMIT_BRANCH == "main" # execution only on main
+
+    variables:
+        CAPELLA_VERSION: 6.1.0
+        ENTRYPOINT: model.aird
+        CAPELLA2POLARION_PROJECT_ID: syncproj
+        CAPELLA2POLARION_MODEL_JSON: '{"path": "PATH_TO_CAPELLA"}'
+        CAPELLA2POLARION_CONFIG: capella2polarion_config.yaml
+        CAPELLA2POLARION_DEBUG: 1
diff --git a/tests/data/model_elements/config.yaml b/tests/data/model_elements/config.yaml
@@ -2,43 +2,43 @@
 # SPDX-License-Identifier: Apache-2.0
 
 "*": # All layers
-      - "*": # All class types
-              - parent # Specify workitem links
-              - description_reference # Custom attribute
-      - Class:
-              - state_machines
-      - Diagram:
-              - diagram_elements
-      - Constraint
+  - "*": # All class types
+      - parent # Specify workitem links
+      - description_reference # Custom attribute
+  - Class:
+      - state_machines
+  - Diagram:
+      - diagram_elements
+  - Constraint
 
 oa: # Specify below
-      - OperationalCapability: # Capella Type with references
-              - involved_activities # Specify workitem links
-              - involved_entities
+  - OperationalCapability: # Capella Type with references
+      - involved_activities # Specify workitem links
+      - involved_entities
 
-      - OperationalActivity # Capella Type w/o references
-      - OperationalEntity # Custom Type maps to Entity
-      - OperationalInteraction # Custom Type maps to FunctionalExchange
-      - CommunicationMean
-      - Class
-      - StateMachine
+  - OperationalActivity # Capella Type w/o references
+  - OperationalEntity # Custom Type maps to Entity
+  - OperationalInteraction # Custom Type maps to FunctionalExchange
+  - CommunicationMean
+  - Class
+  - StateMachine
 
 sa:
-      - SystemComponent:
-              - allocated_functions
-      - SystemActor: # Custom Type that doesn't exist in Capella
-              - allocated_functions
-      - SystemFunction
-      - ComponentExchange:
-              - allocated_functional_exchanges
-      - ComponentPort
-      - FunctionalExchange:
-              - exchanged_items
-      - ExchangeItem
-      - Class
+  - SystemComponent:
+      - allocated_functions
+  - SystemActor: # Custom Type that doesn't exist in Capella
+      - allocated_functions
+  - SystemFunction
+  - ComponentExchange:
+      - allocated_functional_exchanges
+  - ComponentPort
+  - FunctionalExchange:
+      - exchanged_items
+  - ExchangeItem
+  - Class
 
 pa:
-      - PhysicalComponent:
-              - allocated_functions
-      - PhysicalActor:
-              - allocated_functions
+  - PhysicalComponent:
+      - allocated_functions
+  - PhysicalActor:
+      - allocated_functions