docs: Update docs

docs/source/configuration/render_documents.rst

@@ -10,10 +10,10 @@ 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.
 
-Example configuration
----------------------
-The `full_authority_config.yaml` file provides the configuration for rendering
-the document in Full authority mode.
+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
@@ -33,7 +33,7 @@ the Live-Doc is managed.
 
 Mixed Authority Mode
 ********************
-In Mixed authority mode, users have more flexibility over the Live-Doc. In this
+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
@@ -51,6 +51,8 @@ for automated rendering.
    :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:
 

docs/source/configuration/sync.rst

@@ -82,6 +82,8 @@ Polarion types are used. In capellambse however this is just a
 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:
@@ -107,5 +109,5 @@ polarion custom field ID for a grouped list of these links. The
 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.
+``ExchangeItem`` s included. The key "Exchange Items" is used for the
+indication in the list.

docs/source/features/render_documents.rst

@@ -4,8 +4,8 @@
 
 .. _render-documents:
 
-Render Polarion Live-Documents
-==============================
+Render Live-Docs
+================
 The `capella2polarion` service supports rendering and updating Polarion Live
 Documents in two distinct modes: Full authority and Mixed authority. These
 modes control how sections of the Live Document (Live-Doc) are populated and
@@ -15,18 +15,36 @@ completely on its own, managing the complexity of the document layout
 configuration for each work item type. The only thing needed for the service is
 a dedicated Polarion document space, ``_default`` can be used too.
 
-How it works
-------------
-
+The setup and configuration is explained in detail in the :ref:`Live-Docs
+rendering <render-docs-config>` documentation page.
 
 Full Authority Mode
 *******************
 In Full authority mode, the entire Live-Doc is controlled by the
 `capella2polarion` service. During each rendering session, the entire document
 is re-rendered and updated based on the data provided by the Capella model. Any
 manual edits or changes made by a user in Polarion will be overwritten during
-the next synchronization process.
+the next synchronization process if the status is still set to a value in the
+``status_allow_list``. Don't worry comments will persist because everything in
+the rendered Live-Doc is a work item. Headings are reused, free text will be
+created as a work item of type Text. The status feature enables an efficient
+and streamlined review and release process, minimizing disruptions during the
+phases.
+
+It is ensured that the Live-Doc is always consistent with the Capella model and
+Polarion project state, but it means that no manual changes can persist between
+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
+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
+content rendered from Jinja2 templates, while the rest of the document can be
+manually managed and updated by users in Polarion.
 
-This mode ensures that the Live-Doc is always consistent with the Capella
-model and Polarion project state, but it means that no manual changes can
-persist between rendering sessions.
+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.

docs/source/features/sync.rst

@@ -6,10 +6,6 @@
 
 Model synchronization
 =====================
-
-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
@@ -105,15 +101,32 @@ 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.
+If the configuration is done, any Capella attribute can be rendered as a link.
+Per default any configured link will cause the rendering 2 custom fields:
 
-Have a look into
+1. Grouped linked work items
+2. Grouped backlink work items (on the link target work items)
 
 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 in 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.
+document:
+
+.. image:: ../_static/linked_work_items.jpeg
+  :width: 700
+  :align: center
+
+Therefore, Capella2Polarion creates two custom fields for each link configured.
+The linked work items are then grouped: A direct field with a list of the links
+and a field for the reverse links on each target:
+
+.. image:: ../_static/grouped_linked_work_items.png
+  :width: 700
+  :align: center
+
+For now this feature can not be disabled. Keep in mind that this requires
+configuration of 2 new custom fields on the work item type and the targeted
+work item type. See the :ref:`linked work items configuration documentation
+page <links-config>` for more details.