fix(docs): Be more precise in documentation

DSD-DBS · Feb 3, 2023 · ec68ccc · ec68ccc
1 parent fd814ef
commit ec68ccc
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 23 deletions.
diff --git 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 <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
@@ -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 <snapshot>` from the RM software calculating a :ref:`change set
-<change-set>`. This change set can then be applied to a
+:ref:`snapshot <snapshot>` from the RM software calculating a :ref:`ChangeSet
+<change-set>`. 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
@@ -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<declarative-modelling>` syntax of capellambse.
+The snapshot is the input needed for calculating the
+:ref:`ChangeSet<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<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: <p>Test Description</p>
        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