deploy: 6868bef

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d541dbdf3efbb3c4ef6ef54f44c2f954
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/code/capella_ros_tools.rst.txt

@@ -0,0 +1,34 @@
+capella\_ros\_tools package
+===========================
+
+.. automodule:: capella_ros_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+capella\_ros\_tools.data\_model module
+--------------------------------------
+
+.. automodule:: capella_ros_tools.data_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+capella\_ros\_tools.exporter module
+-----------------------------------
+
+.. automodule:: capella_ros_tools.exporter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+capella\_ros\_tools.importer module
+-----------------------------------
+
+.. automodule:: capella_ros_tools.importer
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/code/modules.rst.txt

@@ -0,0 +1,7 @@
+capella-ros-tools
+=================
+
+.. toctree::
+   :maxdepth: 4
+
+   capella_ros_tools

_sources/howtos.rst.txt

@@ -0,0 +1,58 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+.. _howtos:
+
+********
+Examples
+********
+
+This section contains a collection of examples that demonstrate how to use the library.
+
+Using the CLI
+=============
+
+Import ROS2 Messages:
+---------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools \
+   import \
+   -i tests/data/data_model/example_msgs \
+   -m tests/data/empty_project_60 \
+   -l la \
+   --no-deps
+
+Import ROS2 Messages from Git Repository:
+-----------------------------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools \
+   import \
+   -i git+https://github.com/DSD-DBS/dsd-ros-msg-definitions-oss \
+   -m tests/data/empty_project_60 \
+   -l la
+
+Export Capella data package:
+------------------------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools \
+   export \
+   -m tests/data/melody_model_60 \
+   -l la \
+   -o tests/data/melody_msgs
+
+Export Capella data package from Git Repository:
+--------------------------------------------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools \
+   export \
+   -m git+https://github.com/DSD-DBS/coffee-machine \
+   -l oa \
+   -o tests/data/coffee_msgs
+
+.. note::
+   When exporting Capella enumerations, if the enumeration literal values are not defined in the Capella model, the values will be assumed to be 0, 1, 2, 3, etc. and the value's type will be set to unit8.

_sources/index.rst.txt

@@ -0,0 +1,47 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+
+***********************************************
+Welcome to the Capella ROS Tools documentation!
+***********************************************
+
+Overview
+========
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Black
+
+**Date**: |today| **Version**: |Version|
+
+Capella ROS Tools is a command-line application written in Python, designed to facilitate the seamless integration of ROS2 and Capella MBSE tools. Key features include:
+
+* Export Capella model elements as ROS2 message (.msg) files.
+* Import ROS2 message (.msg) files as Capella model elements.
+* Works with local and remote message files/Capella projects.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage
+   howtos
+   messages
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API reference:
+
+   code/modules
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

_sources/messages.rst.txt

@@ -0,0 +1,128 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+.. _messages:
+
+*******************
+ROS2 Message Layout
+*******************
+
+The Capella ROS Tools API expects ROS2 messages to be organized in a specific way:
+
+Package Definition
+==================
+* A package is a directory containing a `msg` directory.
+* The `msg` directory contains `.msg` files which contain class and enum definitions.
+
+::
+
+    folders
+    ├── package1
+    │   └── msg
+    │       ├── class1.msg
+    │       └── types
+    │           └── enum1.msg
+    └── package2
+        └── msg
+            └── class2.msg
+
+The above folder structure would translate to the following package definition (assuming class1.msg, class2.msg contain class definitions and enum1.msg contains an enum definition):
+
+::
+
+    packages
+    ├── Package: package1
+    │   ├── Class: class1
+    │   └── Enum: enum1
+    └── Package: package2
+        └── Class: class3
+
+
+Class Definition
+================
+* A `.msg` file can contain one class definition.
+* The comment at the top of the file followed by an empty line is added to the class description.
+* **Inline Comments:** Comments on the same line as a property definition are directly added to that property's description.
+* **Indented Comment Lines:** Comments on a line of their own but indented are added to the description of the last encountered property.
+* **Block Comments:** Comments on a line of their own and not indented are added to the description of the next properties until an empty line and the block comment has been used.
+
+.. literalinclude:: ../../tests/data/data_model/example_msgs/package1/msg/SampleClass.msg
+  :language: python
+
+
+Enum definition
+===============
+* A `.msg` file can contain multiple enum definitions.
+* Enum names are determined based on the common prefix of all enum literals in the enum definition.
+* If no common prefix exists, the enum name is derived from the file name (excluding the extension).
+* Two or more enums must not have literal names without a common prefix.
+* **Inline Comments:** Comments on the same line as an enum literal definition are directly added to the that enum literal's description.
+* **Indented Comment Lines:** Comments on a line of their own but indented are added to the description of the last encountered enum literal.
+* **Block Comments:** Comments on a line of their own and not indented are added to the description of the next enum definition or the next enum literal definitions until an empty line and the block comment has been used.
+
+.. literalinclude:: ../../tests/data/data_model/example_msgs/package1/msg/types/SampleEnum.msg
+  :language: python
+
+Enum and Class Definition
+=========================
+* A `.msg` file can contain one class definition and multiple enum definitions.
+* Enums without a common literal name prefix are named using the file name plus the suffix "Type".
+* There can only be one or no enum whose literal names do not share a common prefix.
+* Comments at the top of the file are added to the class description.
+* **Inline Comments:** Comments on the same line as a property or enum literal are directly added to the description of that element.
+* **Indented Comment Lines:** Comments on a line of their own but indented are added to the description of the last encountered property or enum literal.
+* **Block Comments:** Comments on a line of their own and not indented are added to the descriptions of the next properties, enum or enum literal until an empty line and the block comment has been used.
+
+.. code-block:: python
+
+  # SampleClassEnum.msg
+  # Properties in SampleClassEnum can reference
+  # enums in the same file.
+
+  # This block comment is added to the
+  # enum description of SampleClassEnumType.
+  byte OK     = 0
+  byte WARN   = 1
+  byte ERROR  = 2
+  byte STALE  = 3
+
+  # This block comment is added to the
+  # enum description of Color.
+  byte COLOR_RED    = 0
+  byte COLOR_BLUE   = 1
+  byte COLOR_YELLOW = 2
+
+  uint8 field1    # This inline comment is added to
+                  # the description of field1.
+  uint8 field2
+
+
+Referencing enums
+=================
+
+In the Same File
+----------------
+*  In files that define a class along with enums, the class properties can reference enums defined in the same file. This can be achieved in two ways:
+
+   * **Name Match:** The property name matches the enum name.
+   * **Type Match:** The property type matches the enum literals type, in which case the updated enum name is derived from the file name plus the property name.
+
+*  Name matching takes precedence over type matching.
+
+.. literalinclude:: ../../tests/data/data_model/example_msgs/package2/msg/SampleClassEnum.msg
+  :language: python
+
+In another file
+---------------
+*  If a property definition references an enum in the comments, the property type is updated based on this reference.
+*  The reference should follow either of the following formats:
+
+   * **cf. <File Name>:** The enum name was derived from the file name (excluding the extension).
+   * **cf. <File Name>, <Common Prefix>_XXX:** The enum name was derived from the longest common prefix of all enum literals in the definition.
+
+.. literalinclude:: ../../tests/data/data_model/example_msgs/package1/msg/SampleEnum.msg
+  :language: python
+
+.. literalinclude:: ../../tests/data/data_model/example_msgs/package1/msg/SampleClass.msg
+  :language: python

_sources/usage.rst.txt

@@ -0,0 +1,36 @@
+..
+   Copyright DB InfraGO AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+.. _usage:
+
+*****
+Usage
+*****
+
+This section describes how to use the Capella ROS Tools CLI.
+
+Import ROS2 Messages:
+----------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools import -i <INPUT> -m <MODEL> -l <LAYER> -o <OUTPUT> --no-deps
+
+*  **-i/--input**, path to folder with .msg files.
+*  **-m/--model**, path to the Capella model.
+*  **-l/--layer**, layer to import the messages to.
+*  **-r/--root**, UUID of the root package to import the messages to.
+*  **-t/--type**, UUID of the types package to import the generated data types to.
+*  **--no-deps**, flag to disable import of ROS2 dependencies (e.g. std_msgs)
+*  **-o/--output**, path to output decl YAML.
+
+Export Capella Model (experimental):
+------------------------------------
+.. code-block:: bash
+
+   python -m capella_ros_tools export -m <MODEL> -l <LAYER> -o <OUTPUT>
+
+* **-m/--model**, path to the Capella model.
+* **-l/--layer**, layer to export the messages from.
+* **-r/--root**, UUID of the root package to export the messages from.
+* **-o/--output**, path to output folder.