docs: Update documentation

docs/source/examples/10 Declarative Modeling.ipynb

@@ -154,29 +154,89 @@
     "            promise_id: cm-port-promise\n",
     "\"\"\"\n",
     "# the below line applies the model_update to the model\n",
-    "decl.apply(model, io.StringIO(model_update))"
+    "decl.apply(model, io.StringIO(model_update), strict=False)"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "and now we can verify the changes by visualizing the context of our system under analysis:"
+    "**Notice**: The `strict=False` was needed since no metadata was included into the\n",
+    "`model_update`:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 6,
    "metadata": {},
+   "outputs": [
+    {
+     "ename": "ValueError",
+     "evalue": "No metadata found.",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn [6], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m decl\u001b[39m.\u001b[39;49mapply(model, io\u001b[39m.\u001b[39;49mStringIO(model_update))\n",
+      "File \u001b[0;32m~/wörk/py-capellambse/capellambse/decl.py:160\u001b[0m, in \u001b[0;36mapply\u001b[0;34m(model, file, strict)\u001b[0m\n\u001b[1;32m    158\u001b[0m \u001b[39mif\u001b[39;00m strict:\n\u001b[1;32m    159\u001b[0m     \u001b[39mif\u001b[39;00m \u001b[39mnot\u001b[39;00m metadata:\n\u001b[0;32m--> 160\u001b[0m         \u001b[39mraise\u001b[39;00m \u001b[39mValueError\u001b[39;00m(\u001b[39m\"\u001b[39m\u001b[39mNo metadata found.\u001b[39m\u001b[39m\"\u001b[39m)\n\u001b[1;32m    162\u001b[0m     _metadata_matches_modelinfo(model, metadata)\n\u001b[1;32m    164\u001b[0m \u001b[39mwhile\u001b[39;00m instructions:\n",
+      "\u001b[0;31mValueError\u001b[0m: No metadata found."
+     ]
+    }
+   ],
+   "source": [
+    "decl.apply(model, io.StringIO(model_update))"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`decl.apply` expects a metadata section and checks the values against the model.info:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from importlib import metadata as imm\n",
+    "\n",
+    "model_update = f\"\"\"\n",
+    "capellambse: {imm.version('capellambse')}\n",
+    "model:\n",
+    "  version: null\n",
+    "  url: null\n",
+    "referencing: explicit\n",
+    "generator: Me, the author\n",
+    "---\n",
+    "{model_update}\n",
+    "\"\"\""
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can verify the changes by visualizing the context of our system under analysis:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
    "outputs": [
     {
      "data": {
-      "image/png": "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",
+      "image/png": "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",
       "text/plain": [
        "<Diagram 'Context of Coffee Machine'>"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 8,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -186,10 +246,15 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Please note: the changes we made are not yet stored - if you like those to be saved you may use `model.save()` method. This will save the model back to where it was loaded from, for example by writing back into local files, or by creating a Git commit and pushing it back to the remote.\n"
+    "Please note: the changes we made are not yet stored - if you like those to be saved you may use `model.save()` method. This will save the model back to where it was loaded from, for example by writing back into local files, or by creating a Git commit and pushing it back to the remote.\n",
+    "\n",
+    "For more information checkout the documentation about the [declarative modelling] feature.\n",
+    "\n",
+    "[declarative modelling]: https://dsd-dbs.github.io/py-capellambse/start/declarative.html"
    ]
   }
  ],
@@ -214,7 +279,7 @@
   "orig_nbformat": 4,
   "vscode": {
    "interpreter": {
-    "hash": "c5ea7dc634d8047a259e5b898f154d237fbe6934b444b1a949475949608d751e"
+    "hash": "68692079392476f3e5957229567211dae86496de106b15869a99d77792561652"
    }
   }
  },

docs/source/start/declarative.rst

@@ -68,9 +68,41 @@ containing YAML, wrap it in :external:class:`io.StringIO`:
 Format description
 ==================
 
-The expected YAML follows a simple format, where a parent object (i.e. an
-object that already exists in the model) is selected, and one or more of three
-different operations is applied to it:
+Metadata
+--------
+.. versionadded:: 0.5.16
+   Added metadata document to the declarative modelling YAML.
+
+The metadata has the following format:
+
+.. code-block:: yaml
+
+   capellambse: 1.0.0
+   model:
+     version: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12
+     url: https://example.com/model.git
+   referencing: explicit
+   generator: Declarative Modelling Generator 1.0.0
+
+It gives information about which model the declarative modelling YAML file
+wants to change, with which capellambse version and generator it was written
+with and the referencing-type. A versioned model (using a gitURL) can be
+uniquely identified by its commit-hash and the repository ``url``. These values
+are checked against the ``model.info`` during ``decl.apply`` when the
+``strict`` parameter is ``True`` (default).
+
+The only accepted referencing-type for ``decl.apply`` is ``explicit``.
+Instructions in the declarative modelling YAML may need additional instructions
+for references such that the changes are correctly displayed in Capella. E.g.
+a delete instruction of a port should be followed by a delete instruction of
+the connected exchanges, since an exchange always needs a source and a target.
+
+Instructions
+------------
+
+The expected instruction document in the YAML follows a simple format, where a
+parent object (i.e. an object that already exists in the model) is selected,
+and one or more of three different operations is applied to it:
 
 - ``extend``-ing the object on list attributes,
 - ``modify``-ing the object itself, or

tests/data/decl/coffee-machine.yml

@@ -3,9 +3,9 @@
 capellambse: 1.0.0
 model:
   version: 12345678
-  url: example.com
+  url: https://example.com/model.git
 referencing: explicit
-generator: example 1.0.0
+generator: Declarative Modelling Generator 1.0.0
 ---
 - parent: !uuid 0d2edb8f-fa34-4e73-89ec-fb9a63001440 # root logical component
   extend: