Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
deploy: 7d9c0c6
Browse files Browse the repository at this point in the history
ewuerger committed Oct 29, 2024
0 parents commit d7c7e4d
Showing 72 changed files with 12,272 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
config: af73100e0889f28b6e637d5e2e7d0baa
tags: 645f666f9bcd5a90fca523b33c5a78b7
Empty file added .nojekyll
Empty file.
Binary file added _images/grouped_linked_work_items.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/linked_work_items.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/mixed-authority-live-doc-divider-down.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/mixed-authority-live-doc-divider-up.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
26 changes: 26 additions & 0 deletions _sources/code/capella2polarion.connectors.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
capella2polarion.connectors package
===================================

.. automodule:: capella2polarion.connectors
:members:
:undoc-members:
:show-inheritance:

Submodules
----------

capella2polarion.connectors.polarion\_repo module
-------------------------------------------------

.. automodule:: capella2polarion.connectors.polarion_repo
:members:
:undoc-members:
:show-inheritance:

capella2polarion.connectors.polarion\_worker module
---------------------------------------------------

.. automodule:: capella2polarion.connectors.polarion_worker
:members:
:undoc-members:
:show-inheritance:
82 changes: 82 additions & 0 deletions _sources/code/capella2polarion.converters.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
capella2polarion.converters package
===================================

.. automodule:: capella2polarion.converters
:members:
:undoc-members:
:show-inheritance:

Submodules
----------

capella2polarion.converters.converter\_config module
----------------------------------------------------

.. automodule:: capella2polarion.converters.converter_config
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.data\_session module
------------------------------------------------

.. automodule:: capella2polarion.converters.data_session
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.document\_config module
---------------------------------------------------

.. automodule:: capella2polarion.converters.document_config
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.document\_renderer module
-----------------------------------------------------

.. automodule:: capella2polarion.converters.document_renderer
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.element\_converter module
-----------------------------------------------------

.. automodule:: capella2polarion.converters.element_converter
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.link\_converter module
--------------------------------------------------

.. automodule:: capella2polarion.converters.link_converter
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.model\_converter module
---------------------------------------------------

.. automodule:: capella2polarion.converters.model_converter
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.polarion\_html\_helper module
---------------------------------------------------------

.. automodule:: capella2polarion.converters.polarion_html_helper
:members:
:undoc-members:
:show-inheritance:

capella2polarion.converters.text\_work\_item\_provider module
-------------------------------------------------------------

.. automodule:: capella2polarion.converters.text_work_item_provider
:members:
:undoc-members:
:show-inheritance:
35 changes: 35 additions & 0 deletions _sources/code/capella2polarion.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
capella2polarion package
========================

.. automodule:: capella2polarion
:members:
:undoc-members:
:show-inheritance:

Subpackages
-----------

.. toctree::
:maxdepth: 4

capella2polarion.connectors
capella2polarion.converters

Submodules
----------

capella2polarion.cli module
---------------------------

.. automodule:: capella2polarion.cli
:members:
:undoc-members:
:show-inheritance:

capella2polarion.data\_models module
------------------------------------

.. automodule:: capella2polarion.data_models
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions _sources/code/modules.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
capella-polarion
================

.. toctree::
:maxdepth: 4

capella2polarion
35 changes: 35 additions & 0 deletions _sources/configuration/polarion.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
..
Copyright DB InfraGO AG and contributors
SPDX-License-Identifier: Apache-2.0
.. _polarion-config:

Polarion
========
In general, if an attribute is not configured, it will not be accepted and the
the Rest API will raise a 400 HTTPError since it expects a plain string
attribute. As we use rich text instead, you need to configure your Polarion
project correctly. For that there is the `Capella2Polarion Project Template`_
which includes icon, custom field and enumeration configuration for a pleasant
capella2polarion synchronization.

.. _Capella2Polarion Project Template: https://github.com/DSD-DBS/capella-polarion-template#polarion-dbs-project-template

In general it is advised to use a separate Polarion project for the model
synchronization. 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 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
match the attributes of the capellambse object (e.g., ``involved_activities``),
or you can define custom attributes that require custom code implementation
(e.g., ``description_reference`` links for references to objects in the
description).
82 changes: 82 additions & 0 deletions _sources/configuration/render_documents.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
..
Copyright DB InfraGO AG and contributors
SPDX-License-Identifier: Apache-2.0
.. _render-docs-config:

Live-Docs rendering
===================
The high-level functionality and use cases are described in the
:ref:`feature <render-documents>` documentation page. Here it is described how
to set up the Live-Docs rendering.

Full Authority Mode
*******************
The ``full_authority_config.yaml`` file provides an example configuration for
rendering documents in full authority mode.

.. literalinclude:: ../../../tests/data/documents/full_authority_config.yaml
:language: yaml
:lines: 4-

This file describes the Jinja2 template for the rendering, the filename, the
location, the Polarion project ID. This means it is possible to populate
Live-Doc spaces of other projects. A status-allow-list handles the statuses on
which the Live-Doc will be updated on. If the status enum isn't provided in the
list and the Live-Doc status is changed to it, the service won't update the
Live-Doc. This facilitates an efficient and streamlined review and release
process, minimizing disruptions.

Each instance is a Live-Doc, possibly targeting a specific model element.
With `work_item_layouts` the representational configuration of work items in
the Live-Doc are managed.

Mixed Authority Mode
********************
The `mixed_config.yaml` file describes how to set up mixed authority mode
Live-Docs for automated rendering.

.. literalinclude:: ../../../tests/data/documents/mixed_config.yaml
:language: yaml
:lines: 4-

.. _mixed-sections-config:

Under `sections` the individual templates are listed to populate the marked
sections from the Live-Doc. The following macro is used as dividers:

.. code-block:: html

<div class="c2pAreaStart" id="IcdContent">
#set($statusList = ["draft", "planned", "inReview"])
#if ($statusList.contains($document.getStatus().id))
<p style="font-weight: bold;background-color: #FFFF00;text-align: center;">
DON'T REMOVE THIS<br>
↓↓↓Below this point all content is autogenerated and will be overwritten↓↓↓
</p>
#end
</div>

This looks then like the following in the Live-Doc:

.. image:: ../_static/mixed-authority-live-doc-divider-down.png

Don't forget to do the same for closing the section:

.. image:: ../_static/mixed-authority-live-doc-divider-up.png

Configuration File Templates
----------------------------
The `config.yaml.j2` file in the `documents` folder serves as the primary
configuration template for the Live-Doc rendering service. This Jinja2 template
defines how data from the Capella model should be structured and rendered into
Polarion Live-Docs.

.. literalinclude:: ../../../tests/data/documents/config.yaml.j2
:language: jinja
:lines: 4-

Using this template, the service can populate sections of the Live-Doc with
content based on the selected rendering mode. When working in Mixed authority
mode, the marked sections in the document will be populated, leaving the
unmarked sections untouched.
113 changes: 113 additions & 0 deletions _sources/configuration/sync.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
..
Copyright DB InfraGO AG and contributors
SPDX-License-Identifier: Apache-2.0
.. _sync-config:

Model synchronization
=====================
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, class types and attributes for matching Capella model elements.
Additionally you have the control of adding relationships with the links key.
Underneath the links key use attributes on the matched capellambse model
object. Make sure that the attribute name is correct, you can use
`capellambse's documentation`__ for that.

__ https://dsd-dbs.github.io/py-capellambse/code/capellambse.model.layers.html

Generic
-------

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 4-26

The "star" 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. This will be
merged into layer specific configuration for ``Class`` if there is any.

Serializers
-----------

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 33-34

With ``serializer`` you can control which function is called to render the
:py:class:`capella2polarion.data_models.CapellaWorkItem`. There is a generic
serializer including title (name), description and requirement types, taken per
default. You may also define multiple serializers by providing a list of
serializers in the configs. These will be called in the order provided in the
list. Some serializers also support additional configuration. This can be done
by providing a dictionary of serializers with the serializer as key and the
configuration of the serializer as value. For example ``Class`` using the
``add_tree_diagram`` serializer:

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 9-13

or ``SystemFunction`` with the ``add_context_diagram`` serializer using ``filters``:

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 64-67

If a serializer supports additional parameters this will be documented in the
supported capella serializers table in :ref:`Model synchronization
<supported_capella_serializers>`.

Different capella type and polarion type ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 29-30

Sometimes capellambse class types are not the same in Polarion. In order to
handle this case you can use the ``polarion_type`` key to map capellambse types
to the desired Polarion type.

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 73-91

For the ``PhysicalComponent`` you can see this in extreme action, where based
on the different permutation of the attributes actor and nature different
Polarion types are used. In capellambse however this is just a
``PhysicalComponent``. Combining this with ``links`` is possible too. You can
configure a generic config and for each specific config you can also add a
``links`` section. Both will be merged.

.. _links-config:

Links
-----
Links can be configured by just providing a list of strings:

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 33-37

However there is a more verbose way that gives you the option to configure the
link further:

.. literalinclude:: ../../../tests/data/model_elements/config.yaml
:language: yaml
:lines: 52-63

The links of ``SystemFunction`` are configured such that a ``polarion_role``,
a separate ``capella_attr``, an ``include``, ``link_field`` and
``reverse_field`` is defined. In this example the ``capella_attr`` is utilizing
the map functionality of capellambse. You can therefore chain attributes using
a ``.`` to get to the desired elements for your link. The ``link_field`` is the
polarion custom field ID for a grouped list of these links. The
``reverse_field`` is the polarion custom field ID for the grouped backlinks of
the links. The ``include`` is an optional feature that renders additional
work item references into the grouped link custom field. In this example for
each linked ``FunctionalExchange`` in the grouped list there will be
``ExchangeItem`` s included. The key "Exchange Items" is used for the
indication in the list.
Loading

0 comments on commit d7c7e4d

Please sign in to comment.