fix: Accumulate comment lines

capella_ros_tools/__main__.py

@@ -10,6 +10,7 @@
 from capellambse import cli_helpers, decl
 
 import capella_ros_tools
+from capella_ros_tools import exporter, importer
 
 
 @click.group()
@@ -28,17 +29,21 @@ def cli():
     "--input",
     type=str,
     required=True,
+    help="Path to the ROS message package.",
 )
 @click.option(
-    "-m" "--model",
+    "-m",
+    "--model",
     type=cli_helpers.ModelCLI(),
     required=True,
+    help="Path to the Capella model.",
 )
 @click.option(
     "-l",
     "--layer",
     type=click.Choice(["oa", "la", "sa", "pa"], case_sensitive=False),
     required=True,
+    help="The layer to import the messages to.",
 )
 @click.option(
     "--no-deps",
@@ -47,56 +52,58 @@ def cli():
     help="Don’t install message dependencies.",
 )
 @click.option(
-    "-p", "--port", type=int, help="Open model viewer on given port."
+    "-o",
+    "--output",
+    type=click.Path(path_type=pathlib.Path, dir_okay=False),
+    help="Output file path for decl YAML.",
 )
 def import_msgs(
     input: str,
     model: capellambse.MelodyModel,
     layer: str,
     no_deps: bool,
-    port: int,
+    output: pathlib.Path,
 ) -> None:
     """Import ROS messages into a Capella data package."""
 
-    from capella_ros_tools.scripts import import_msgs as importer
-
     root_uuid = getattr(model, layer).uuid
     types_uuid = model.sa.data_package.uuid
 
-    yml = importer.Importer(input, no_deps)(root_uuid, types_uuid)
-    decl.apply(model, io.StringIO(yml))
-
-    if port:
-        raise NotImplementedError("Open model with model explorer.")
+    yml = importer.Importer(input, no_deps).to_yaml(root_uuid, types_uuid)
+    if output:
+        output.write_text(yml, encoding="utf-8")
+    else:
+        decl.apply(model, io.StringIO(yml))
 
 
 @cli.command("export")
-@click.option("-m", "--model", type=cli_helpers.ModelCLI, required=True)
+@click.option(
+    "-m",
+    "--model",
+    type=cli_helpers.ModelCLI,
+    required=True,
+    help="Path to the Capella model.",
+)
 @click.option(
     "-l",
     "--layer",
     type=click.Choice(["oa", "la", "sa", "pa"], case_sensitive=False),
     required=True,
+    help="The layer to export the model objects from.",
 )
 @click.option(
     "-o",
     "--output",
-    type=click.Path(path_type=pathlib.Path),
+    type=click.Path(path_type=pathlib.Path, file_okay=False),
     default=pathlib.Path.cwd() / "export",
+    help="Output directory for the .msg files.",
 )
 def export_capella(
     model: capellambse.MelodyModel,
     layer: str,
     output: pathlib.Path,
 ):
-    """Export Capella data package to ROS messages.
-
-    CAPELLA_PATH: Path to Capella model.
-    LAYER: Layer of Capella model to export elements from.
-    MESSAGES: Path to output folder for .msg files.
-    """
-    from capella_ros_tools.scripts import export_capella as exporter
-
+    """Export Capella data package to ROS messages."""
     current_pkg = getattr(model, layer).data_package
     exporter.export(current_pkg, output)
 

capella_ros_tools/data_model.py

@@ -150,6 +150,13 @@ def __eq__(self, other: object) -> bool:
         )
 
 
+def _process_block_comment(line: str) -> str:
+    if comment := _clean_comment(line):
+        return f"{comment} "
+    else:
+        return "<br>"
+
+
 def _extract_file_level_comments(
     msg_string: str,
 ) -> t.Tuple[str, list[str]]:
@@ -165,7 +172,7 @@ def _extract_file_level_comments(
                 return "", lines
             else:
                 break
-        file_level_comments += f"<p>{_clean_comment(line)}</p>"
+        file_level_comments += _process_block_comment(line)
 
     file_content = lines[i:]
     return file_level_comments, file_content
@@ -240,16 +247,19 @@ def from_string(cls, msg_name: str, msg_string: str) -> MessageDef:
                 if last_index > 0:
                     # block comments were used
                     block_comments = ""
-                block_comments += f"<p>{_clean_comment(line)}</p>"
+                block_comments += _process_block_comment(line)
                 continue
             else:
                 # inline comment
-                comment = f"<p>{_clean_comment(line[index:])}</p>"
+                comment = _clean_comment(line[index:])
                 line = line[:index].rstrip()
                 if not line:
                     # indented comment
-                    last_element.description += comment
+                    last_element.description += (
+                        f"{comment} " if comment else "<br>"
+                    )
                     continue
+                comment = f"{comment} "
 
             type_string, _, rest = line.partition(" ")
             name, _, value = rest.partition(CONSTANT_SEPARATOR)
@@ -288,6 +298,11 @@ def from_string(cls, msg_name: str, msg_string: str) -> MessageDef:
             common_prefix = os.path.commonprefix(
                 [literal.name for literal in enum.literals]
             )
+            if not common_prefix.endswith("_"):
+                if index := common_prefix.rfind("_"):
+                    common_prefix = common_prefix[: index + 1]
+                else:
+                    common_prefix = ""
             if common_prefix:
                 enum.name = _get_enum_identifier(common_prefix)
                 for literal in enum.literals:

capella_ros_tools/scripts/import_msgs.py → capella_ros_tools/importer.py

@@ -4,17 +4,16 @@
 
 import logging
 
-import capellambse
 from capellambse import decl, filehandler, helpers
-from capellambse.filehandler import abc
 
 from capella_ros_tools import data_model
 
 ROS2_INTERFACES = {
     "common_interfaces": "git+https://github.com/ros2/common_interfaces",
     "rcl_interfaces": "git+https://github.com/ros2/rcl_interfaces",
-    "unique_identifier_msgs": "git+https://github.com"
-    "/ros2/unique_identifier_msgs",
+    "unique_identifier_msgs": (
+        "git+https://github.com/ros2/unique_identifier_msgs"
+    ),
 }
 
 
@@ -181,7 +180,7 @@ def _convert_enum(self, enum_def: data_model.EnumDef) -> dict:
 
         return yml
 
-    def __call__(self, layer_data_uuid: str, sa_data_uuid) -> str:
+    def to_yaml(self, layer_data_uuid: str, sa_data_uuid) -> str:
         """Import ROS messages into a Capella data package."""
         instructions = self._convert_package(
             decl.UUIDReference(helpers.UUIDString(layer_data_uuid)),

docs/source/messages.rst

@@ -10,6 +10,35 @@ 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.