From 4ef81c3534f0f0db6424077f1966cf4e60c0c3b4 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Wed, 31 Jan 2024 18:43:15 +0100 Subject: [PATCH] docs: Add feature overview --- .../converters/model_converter.py | 2 +- capella2polarion/data_models.py | 2 +- docs/source/features.rst | 103 ++++++++++++++++++ docs/source/index.rst | 20 ++-- 4 files changed, 116 insertions(+), 11 deletions(-) create mode 100644 docs/source/features.rst diff --git a/capella2polarion/converters/model_converter.py b/capella2polarion/converters/model_converter.py index 470287aa..66bafd24 100644 --- a/capella2polarion/converters/model_converter.py +++ b/capella2polarion/converters/model_converter.py @@ -94,7 +94,7 @@ def generate_work_items( ) -> dict[str, data_models.CapellaWorkItem]: """Return a work items mapping from model elements for Polarion. - The dictionary maps Capella UUIDs to ``CapellaWorkItem``s. In + The dictionary maps Capella UUIDs to ``CapellaWorkItem`` s. In addition, it is ensured that neither title nor type are None, Links are not created in this step by default. """ diff --git a/capella2polarion/data_models.py b/capella2polarion/data_models.py index d022f4b6..2f750e7e 100644 --- a/capella2polarion/data_models.py +++ b/capella2polarion/data_models.py @@ -9,7 +9,7 @@ class CapellaWorkItem(polarion_api.WorkItem): - """A custom WorkItem class with additional capella related attributes.""" + """A WorkItem class with additional Capella related attributes.""" class Condition(t.TypedDict): """A class to describe a pre or post condition.""" diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 00000000..4d0ef4fb --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,103 @@ +.. + Copyright DB InfraGO AG and contributors + SPDX-License-Identifier: Apache-2.0 + +.. _features: + +How it works +============ +The synchronization of Capella objects as Polarion work items is done by using +the Polarion REST API. We developed a `Python client`_ where most of the +endpoints are generated from the open API description. In general we serialize +all Capella objects fetched from the ``capellambse.MelodyModel`` instance +inferred from the capella2polarion config. Then in order to reduce the request +amount we compare a checksum of the existing work items and the newly created +ones. If the checksum differs a patch request will happen. If there doesn't +exist a work item with a ``capella_uuid`` yet, a new work item will be created. +These custom fields ``_checksum`` and ``_capella_uuid`` are required. +Per default capella2polarion will not delete any work items but set the status +to deleted. With the ``--delete`` flag however you can enable the deletion. + +.. _Python client: https://github.com/DSD-DBS/capella-polarion-template#polarion-dbs-project-template + +Features +-------- + +Supported Capella types +*********************** + +Capella2Polarion lets you synchronize the following attributes through the +specific serializer alone: + ++--------------------------------------+------------------------------------------------------+ +| Serializer | Description | ++======================================+======================================================+ +| generic_work_item | The default serializer for Capella objects w/o a | +| | specific serializer. All other serializers are | +| | reusing the generic serializer. | +| | This serializer populates: type, title, | +| | description, status, uuid_capella amd | +| | requirement_types. The requirement type fields | +| | are inferred from the requirement type (this is | +| | the custom field name/id) and the value is then | +| | the requirement's text. | ++--------------------------------------+------------------------------------------------------+ +| diagram | A serializer for Capella diagrams. Currently the | +| | diagram is taken from the diagram_cache, served | +| | from a GitLab artifact URL and embedded as a b64 | +| | encoded SVG. | ++--------------------------------------+------------------------------------------------------+ +| include_pre_and_post_condition | A serializer adding post- and precondition | +| | fields. Usually taken for ``Capability`` s. | ++--------------------------------------+------------------------------------------------------+ +| linked_text_as_description | A serializer resolving ``Constraint`` s and their | +| | linked text. | ++--------------------------------------+------------------------------------------------------+ +| add_context_diagram | A serializer adding a context diagram to the work | +| | item. This requires node.js to be installed. | +| | The Capella objects where ``context_diagram`` is | +| | available can be seen in the `context-diagrams | +| | documentation`_. | ++--------------------------------------+------------------------------------------------------+ +| add_tree_view | A serializer adding a tree view diagram to the | +| | work item. Same requirements as for | +| | ``add_context_diagram``. `Tree View Documentation`_. | ++--------------------------------------+------------------------------------------------------+ + +.. _context-diagrams documentation: https://dsd-dbs.github.io/capellambse-context-diagrams/#context-diagram-extension-for-capellambse +.. _Tree View documentation: https://dsd-dbs.github.io/capellambse-context-diagrams/tree_view/ + +Links +***** + +Attributes on Capella objects referencing other Capella objects are rendered +as linked work items if (and only if) the link target exists as a work item in +Polarion. This needs specific configuration in the work item link roles XML. +If the configuration is done, any attribute can be rendered as a link. + +Grouped linked work items +************************* + +In a Polarion live-doc there is no way to filter the linked work items table +which is automatically created from Polarion and can be included into the +document. Therefore Capella2Polarion creates two custom fields for each link +group: A direct field with a list of the links and a field for the reverse +links on each target. + +Roadmap +------- + +We try to work on all issues listed in the `GitHub issues board`_. However in +the nearest future (max. 2 weeks) we want to solve the following problems: + +- Instead of embedding SVGs in the description > attach the SVG and optionally + a PNG. Additonal checksums are made for the work item and each individual + attachment. +- New serializers > support of more Capella types +- Improved logging for CI/CD Pipeline verbosity +- Bug fixes... + +It is planned that with the end of April 2024 Capella2Polarion will be +published and available via PyPI. + +.. _GitHub issues board: https://github.com/DSD-DBS/capella-polarion/issues diff --git a/docs/source/index.rst b/docs/source/index.rst index eaea7ca2..6e8c6f1c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,16 +14,12 @@ Migrate any model element from a ``capellambse.MelodyModel`` to Polarion as a 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 is attached to the respective work item. -With appropriate :ref:`configuration ` on Polarion -and an according :ref:`config YAML file ` 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. +With appropriate :ref:`configuration ` on Polarion and +an according config YAML file for capella2polarion any model element can be +migrated from a Capella model to a Polarion project. For an overview over all +features and supported Capella object types have a look into the :ref:`features +and roadmap ` documentation page. .. _capella diagram cache: https://github.com/DSD-DBS/capella-dockerimages/blob/main/ci-templates/gitlab/diagram-cache.yml @@ -39,6 +35,12 @@ differ the old will be patched by the new one. pipeline templates/gitlab +.. toctree:: + :maxdepth: 2 + :caption: Features and Roadmap: + + features + .. toctree:: :maxdepth: 3 :caption: API reference