From ec68ccc8d4a43ee1f714d5ab3d817a5b4816b2d2 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Fri, 3 Feb 2023 14:15:48 +0100 Subject: [PATCH] fix(docs): Be more precise in documentation --- docs/source/changeset.rst | 4 ++-- docs/source/index.rst | 4 ++-- docs/source/snapshot.rst | 41 +++++++++++++++++++++------------------ 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/source/changeset.rst b/docs/source/changeset.rst index 2231732..af68818 100644 --- a/docs/source/changeset.rst +++ b/docs/source/changeset.rst @@ -8,7 +8,7 @@ ChangeSet ********* -The change set is the output of +The ChangeSet is the output of :py:func:`~capella_rm_bridge.changeset.calculate_change_set` and uses the :ref:`declarative modelling ` syntax of capellambse. An example for the initial migration of the snapshot example: @@ -17,7 +17,7 @@ example for the initial migration of the snapshot example: :language: yaml :lines: 4- -The following change set shows modifications (i.e. synchronizations) after the +The following ChangeSet shows modifications (i.e. synchronizations) after the initial migration: .. literalinclude:: ../../tests/data/changesets/mod.yaml diff --git a/docs/source/index.rst b/docs/source/index.rst index dc12bc4..6d8cffd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,8 +18,8 @@ Capella-RM-Bridge This library was designed to enable and support outsourcing requirements management for Capella_ models via specific RM tools like `Codebeamer`_ or SIEMENS' `Polarion`_. So all this library does is, based on an exported -:ref:`snapshot ` from the RM software calculating a :ref:`change set -`. This change set can then be applied to a +:ref:`snapshot ` from the RM software calculating a :ref:`ChangeSet +`. This ChangeSet can then be applied to a :external:class:`~capellambse.model.MelodyModel` instance from the `capellambse`_ headless model API. diff --git a/docs/source/snapshot.rst b/docs/source/snapshot.rst index b7b24a8..8a8087f 100644 --- a/docs/source/snapshot.rst +++ b/docs/source/snapshot.rst @@ -8,13 +8,14 @@ Snapshot ******** -The snapshot is the input needed for calculating the change set and is a list -of modules. Each module will be compared against a matching -:external:class:`~capellambse.extensions.reqif.CapellaModule` -from the given model. If no matching ``CapellaModule`` was found this -module will be skipped. Differences of the module snapshot and the model -``CapellaModule`` will result in change actions according to the -:ref:`declarative modelling` syntax of capellambse. +The snapshot is the input needed for calculating the +:ref:`ChangeSet` and is a list of modules. Each module will be +compared against a matching +:external:class:`~capellambse.extensions.reqif.CapellaModule` from the given +model. If no matching ``CapellaModule`` was found this module will be skipped. +Differences of the module snapshot and the model ``CapellaModule`` will result +in change actions according to the :ref:`declarative +modelling` syntax of capellambse. Module description ================== @@ -67,6 +68,16 @@ mapping from ``long_name`` to its values. - Feature Rel. 1 - Feature Rel. 2 +In order to have a nice display of ``ValueAttribute``\ s for ``Requirement``\ s +in Capella and also functioning ``.values`` for +:external:class:`~capellambse.extensions.reqif.EnumerationValueAttribute`\ +s, :external:class:`~capellambse.extensions.reqif.AttributeDefinition` +and +:external:class:`~capellambse.extensions.reqif.AttributeDefinitionEnumeration`\ +s are needed. The *data_types* subsection is a ``long_name`` to value (values) +mapping that are matched against the attribute-definitions (``attributes``) +subsection in :ref:`requirement_types`. + .. warning:: The current format does not allow for equally named @@ -133,8 +144,10 @@ and for these a type-hint via ``type`` is needed. text:

Test Description

type: system_requirement # WorkItemType ID - attributes: - Type: [Unset] # Fields for a Folder + attributes: # Fields for a Folder + Capella ID: R-FNC-00001 # String Attribute + Type: [Unset] # Enum Attribute + Submitted at: 2022-06-30 17:07:18.664000+02:00 children: # Folder b/c non-empty children - id: REQ-002 @@ -163,16 +176,6 @@ are supported: - ``EnumerationValueAttribute`` (required as a sequence of strings value in the snapshot) -In order to have a nice display of these ``ValueAttribute``\ s in Capella and -also functioning ``.values`` for -:external:class:`~capellambse.extensions.reqif.EnumerationValueAttribute`\ -s, :external:class:`~capellambse.extensions.reqif.AttributeDefinition` -and -:external:class:`~capellambse.extensions.reqif.AttributeDefinitionEnumeration`\ -s are needed. This subsection is a ``long_name`` to value (values) mapping that -are matched against the attribute-definitions (``attributes``) subsection in -:ref:`requirement_types`. - .. note:: During execution of