Merge branch 'improve-docs' of github.com:DSD-DBS/capella-polarion in…

…to improve-docs

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

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

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

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

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

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 <mixed-sections-config>`. 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 <render-docs-config>`.

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 <sync-config>` of the service and on
-  :ref:`Polarion <polarion-config>` 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 <sync>` 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 <render-documents>` documentation page. For a
-  guide on how this service is configured see the :ref:`configuration page
-  <render-docs-config>`.
+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 <sync-config>` of the service and on
+:ref:`Polarion <polarion-config>` 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 <sync>` 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 <render-documents>` documentation page. For a guide on
+how this service is configured see the :ref:`configuration page
+<render-docs-config>`.
 
 .. note:: Additional features will be documented here in the future as they are developed and integrated.
 

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