From b7ed1b4f50b538ae1db0b8960892c32590c832f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ernst=20W=C3=BCrger?= Date: Mon, 23 Sep 2024 10:34:24 +0200 Subject: [PATCH 1/3] ci: Add missing license headers --- docs/source/_static/grouped_linked_work_items.png.license | 2 ++ docs/source/_static/linked_work_items.jpeg.license | 2 ++ .../_static/mixed-authority-live-doc-divider-down.png.license | 2 ++ .../_static/mixed-authority-live-doc-divider-up.png.license | 2 ++ docs/source/roadmap.rst | 4 ++++ 5 files changed, 12 insertions(+) create mode 100644 docs/source/_static/grouped_linked_work_items.png.license create mode 100644 docs/source/_static/linked_work_items.jpeg.license create mode 100644 docs/source/_static/mixed-authority-live-doc-divider-down.png.license create mode 100644 docs/source/_static/mixed-authority-live-doc-divider-up.png.license diff --git a/docs/source/_static/grouped_linked_work_items.png.license b/docs/source/_static/grouped_linked_work_items.png.license new file mode 100644 index 0000000..370532f --- /dev/null +++ b/docs/source/_static/grouped_linked_work_items.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and the capellambse contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/source/_static/linked_work_items.jpeg.license b/docs/source/_static/linked_work_items.jpeg.license new file mode 100644 index 0000000..370532f --- /dev/null +++ b/docs/source/_static/linked_work_items.jpeg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and the capellambse contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/source/_static/mixed-authority-live-doc-divider-down.png.license b/docs/source/_static/mixed-authority-live-doc-divider-down.png.license new file mode 100644 index 0000000..370532f --- /dev/null +++ b/docs/source/_static/mixed-authority-live-doc-divider-down.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and the capellambse contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/source/_static/mixed-authority-live-doc-divider-up.png.license b/docs/source/_static/mixed-authority-live-doc-divider-up.png.license new file mode 100644 index 0000000..370532f --- /dev/null +++ b/docs/source/_static/mixed-authority-live-doc-divider-up.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and the capellambse contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/source/roadmap.rst b/docs/source/roadmap.rst index 072e8e8..4c5fa4f 100644 --- a/docs/source/roadmap.rst +++ b/docs/source/roadmap.rst @@ -1,4 +1,8 @@ +.. + Copyright DB InfraGO AG and contributors + SPDX-License-Identifier: Apache-2.0 + Polarion config diff/mig tool ============================= The model element synchronization is a service that requires configuration From 899cca8a6f7838833b4f449718162ef17fa6b09f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ernst=20W=C3=BCrger?= Date: Mon, 23 Sep 2024 10:55:28 +0200 Subject: [PATCH 2/3] docs: Update render-documents --- docs/source/configuration/render_documents.rst | 15 ++------------- docs/source/features/render_documents.rst | 5 ++++- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/docs/source/configuration/render_documents.rst b/docs/source/configuration/render_documents.rst index 646d69e..74a3517 100644 --- a/docs/source/configuration/render_documents.rst +++ b/docs/source/configuration/render_documents.rst @@ -29,23 +29,12 @@ 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 is managed. +the Live-Doc are managed. Mixed Authority Mode ******************** -In mixed authority mode, users have more flexibility over the Live-Doc. In this -mode, users can mark specific sections of the Live-Doc where they would like -content to be inserted or updated by the `capella2polarion` service. These -sections are populated with content rendered from Jinja2 templates, while the -rest of the document can be manually managed and updated by users in Polarion. - -This allows users to maintain manual changes in non-synchronized sections of -the document, while still benefiting from automated updates for key sections. - -Example Configuration: - The `mixed_config.yaml` file describes how to set up mixed authority mode -for automated rendering. +Live-Docs for automated rendering. .. literalinclude:: ../../../tests/data/documents/mixed_config.yaml :language: yaml diff --git a/docs/source/features/render_documents.rst b/docs/source/features/render_documents.rst index 40c67c3..eb84097 100644 --- a/docs/source/features/render_documents.rst +++ b/docs/source/features/render_documents.rst @@ -38,7 +38,7 @@ rendering sessions. Mixed Authority Mode ******************** In mixed authority mode, users have more flexibility over the Live-Doc. Users -can mark (via macro) specific sections of the Live-Doc where they would like +can mark specific sections of the Live-Doc via wiki-macro where they would like content to be inserted or updated by the `capella2polarion` service. If you want to see how this looks like, have a look in the :ref:`configuration documentation page `. These sections are populated with @@ -48,3 +48,6 @@ manually managed and updated by users in Polarion. This allows users to maintain manual changes in non-synchronized sections of the document, while still benefiting from automated updates for key sections filled with model enhanced content. + +If you want to know how to setup the Live-Doc rendering, head to the +:ref:`documentation page `. From fce7ffc5b491d4aefff467e42fde387b0cc5d6d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ernst=20W=C3=BCrger?= Date: Mon, 23 Sep 2024 11:43:18 +0200 Subject: [PATCH 3/3] docs: Remove unnecessary heading --- docs/source/index.rst | 76 ++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 40 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 1bdf568..afc78f8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,46 +12,42 @@ Overview capella2polarion offers several features to interact with Polarion and Capella models. Currently, the following features are available: -Available Features ------------------- - -- **Synchronization of Model-Elements** - - 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. - - With appropriate :ref:`configuration ` of the service and on - :ref:`Polarion ` any model element can be migrated from a - Capella model to a Polarion project. For an overview of all features related - to the synchronization and supported Capella object types, have a look at the - :ref:`model synchronization ` documentation page. - -- **Rendering of Live-Documents** - - The `render_documents` command in the CLI allows the rendering of Polarion - Live-Documents in a dedicated documents space inside a Polarion project. This - doesn't need to be the sync project. These documents are generated via - rendering Jinja2 templates, enabling them to be enriched by model data - without requiring the data as a work item in Polarion. - - There are two modes for rendering Live-Documents: - - - **Full Authority Documents**: C2P takes full control over the content, and - any human-made changes to the document will be overwritten in the next - rendering cycle. To make changes persistent, modifications to the Jinja2 - templates are required. - - - **Mixed Authority Documents**: C2P takes control over marked sections of - the document, allowing for collaboration where dedicated model-enhanced - areas coexist with human-edited content. - - Detailed information on the Live-Document rendering feature can be found in - the :ref:`render documents ` documentation page. For a - guide on how this service is configured see the :ref:`configuration page - `. +Synchronization of Model-Elements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. + +With appropriate :ref:`configuration ` of the service and on +:ref:`Polarion ` any model element can be migrated from a +Capella model to a Polarion project. For an overview of all features related to +the synchronization and supported Capella object types, have a look at the +:ref:`model synchronization ` documentation page. + +Rendering of Live-Documents +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The `render_documents` command in the CLI allows the rendering of Polarion +Live-Documents in a dedicated documents space inside a Polarion project. This +doesn't need to be the sync project. These documents are generated via +rendering Jinja2 templates, enabling them to be enriched by model data without +requiring the data as a work item in Polarion. + +There are two modes for rendering Live-Documents: + +- **Full Authority Documents**: C2P takes full control over the content, and + any human-made changes to the document will be overwritten in the next + rendering cycle. To make changes persistent, modifications to the Jinja2 + templates are required. + +- **Mixed Authority Documents**: C2P takes control over marked sections of + the document, allowing for collaboration where dedicated model-enhanced + areas coexist with human-edited content. + +Detailed information on the Live-Document rendering feature can be found in the +:ref:`render documents ` documentation page. For a guide on +how this service is configured see the :ref:`configuration page +`. .. note:: Additional features will be documented here in the future as they are developed and integrated.