docs: Add feature overview

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.
         """

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."""

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

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 <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.
+With appropriate :ref:`configuration <capella2polarion-config>` 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 <features>` 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