Add update verb (#48)

3473f · pre-commit-ci[bot] · web-flow · commit f7ba590caf1c · 2025-02-02T09:43:24.000+01:00
* Add update.py * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * initial document parser * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * rename type to data_type * add update verb to entry_points * initial update documentation * update parameters * from dict to lists * create Node class * get running node interface * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Pump version to 1.1.0 * WIP * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add update.py * initial document parser * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * rename type to data_type * add update verb to entry_points * initial update documentation * update parameters * from dict to lists * create Node class * get running node interface * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Pump version to 1.1.0 * WIP * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * remove unused code * Update version to 1.2.0 * Remove unused Node class * add node_name as an argument * Implement DocParser * fix bug with description * get nodes and interfaces * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * style changes * style changes * WIP: update doc method * handle same params but different types and describtions * remove white space * WIP: doc updater * Delet the removed APIs * Up the version to 2.2.0 * Update README.md * Update README.md --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -6,27 +6,19 @@
 
 ## Overview
 
-The `ros2autodoc` package provides a ROS2 command line interface tool to automatically generate documentation for ROS2 nodes.
-The tool outputs an initial documentation file detailing the interface (parameters, publishers, subscribers, services and actions) for a running ROS2 node. The package was tested with ROS2 Foxy, Humble and Iron.
+The `ros2autodoc` package extends the ROS 2 CLI tools to generate API documentation for ROS2 nodes, update previously generated documentation or check if a node is documented for use in CI/CD jobs. The tool outputs a markdown file in the style of ROS Wiki.
 
 ## Installation
 
-1. Install a recent ROS2 version.
-2. Make sure that `colcon` is installed:
-
-```shell
-sudo apt install python3-colcon-common-extensions
-```
-
-3. Clone this repo into your workspace:
+1. Clone this repo into your workspace:
 
 ```shell
 mkdir -p ~/ros2_ws/src
 cd ~/ros2_ws
 git clone https://github.com/3473f/ros2autodoc src/ros2autodoc
 ```
 
-4. Build the workspace:
+2. Build the workspace:
 
 ```shell
 colcon build
@@ -40,7 +32,9 @@ source install/setup.bash
 ```shell
 $ ros2 autodoc generate --help
 
-usage: ros2 autodoc generate [-h] [--nodes [node ...]] [--executables [executables ...]] [--output-dir] [--seperate-files] package_name
+usage: ros2 autodoc generate [-h] [--nodes [node ...]] [--executables [executables ...]] [--launch-file launch_file]
+                             [--output-dir] [--seperate-files]
+                             package_name
 
 Automatically generate documentation for a ROS2 node
 
@@ -52,8 +46,12 @@ options:
   --nodes [node ...]    name of the nodes to be documented.
   --executables [executables ...]
                         name of the executables for the nodes to be documented.
-  --output-dir          the directory where documentation should be written. If not specified, the file will be saved to the current directory.
-  --seperate-files      when this option is set, the node documentation will be written to separate files and no package documentation will be generated
+  --launch-file launch_file
+                        name of the launch file to start the nodes.
+  --output-dir          the directory where documentation should be written. If not specified, the file will be saved
+                        to the current directory.
+  --seperate-files      when this option is set, the node documentation will be written to separate files and no
+                        package documentation will be generated.
 
 ```
 
@@ -72,7 +70,7 @@ This should output the following [README.md](https://github.com/3473f/ros2autodo
 ```shell
 $ ros2 autodoc check --help
 
-usage: ros2 autodoc check [-h] [--nodes [node ...]] [--executables [executables ...]] package_name input_file
+usage: ros2 autodoc check [-h] [--launch-file launch_file] [--nodes [node ...]] [--executables [executables ...]] package_name input_file
 
 Check if a ROS2 node API is documented
 
@@ -82,6 +80,8 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --launch-file launch_file
+                        name of the launch file to start the nodes.
   --nodes [node ...]    name of the nodes to be documented.
   --executables [executables ...]
                         name of the executables for the nodes to be documented.
@@ -100,3 +100,18 @@ This should output the following and exit
 ```shell
 Node 'turtlesim' interfaces are correctly listed.
 ```
+
+### Update
+
+```shell
+usage: ros2 autodoc update [-h] [node ...] input_file
+
+Update the documentation of a ROS2 node
+
+positional arguments:
+  node        name of the nodes to be documented. If not specified, all running nodes from the package will be documented.
+  input_file  absolute path of the README.md file to be updated.
+
+options:
+  -h, --help  show this help message and exit
+```
diff --git a/package.xml b/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="3">
   <name>ros2autodoc</name>
-  <version>2.1.2</version>
+  <version>2.2.0</version>
   <description>
     The ROS2 autodoc project provides a CLI command to automatically generate ROS-Wiki-style documentation template nodes in markdown syntax.
   </description>
diff --git a/ros2autodoc/api/__init__.py b/ros2autodoc/api/__init__.py
@@ -8,10 +8,13 @@
 # ROS2 pkg API
 from ros2pkg.api import get_executable_paths, get_package_names
 
+from ros2autodoc.api.doc_parser import DocParser
 from ros2autodoc.api.doc_parser import DocParser
 from ros2autodoc.api.doc_writer import DocWriter
 from ros2autodoc.api.node_interface_collector import NodeInterfaceCollector
 
+TODO = "TODO: description"
+
 
 def check_for_package(package_name):
     """Check if the given package is available."""
@@ -116,3 +119,123 @@ def check_interface(interface_type, doc_interface, node_interface):
                 print(f"Type of '{doc_item}' {interface_type} doesn't match.")
                 return False
     return True
+
+
+def update_documentation(node, node_name, file_path):
+    """Update the documentation for the given node."""
+    # Parse the document
+    parser = DocParser(file_path)
+    parser.parse()
+    doc_interface = parser.get_node_interface(node_name)
+    if not doc_interface:
+        print(f"Node '{node_name}' was not found in the documentation.")
+        return
+
+    # Get the current node interface
+    interface_collector = NodeInterfaceCollector(node, node_name)
+    node_interface = interface_collector.get_interfaces()
+
+    # Check if parameter names are the same
+    for node_param in node_interface["parameters"]:
+        if node_param in doc_interface["parameters"]:
+            # Update type if different
+            if node_interface["parameters"][node_param]["type"] != doc_interface["parameters"][node_param]["type"]:
+                print(f"Updating parameter type for {node_param}")
+                doc_interface["parameters"][node_param]["type"] = node_interface["parameters"][node_param]["type"]
+            # Update description if different and not TODO
+            if node_interface["parameters"][node_param]["description"] != doc_interface["parameters"][node_param]["description"] and node_interface["parameters"][node_param]["description"] != TODO:
+                print(f"Updating parameter description for {node_param}")
+                doc_interface["parameters"][node_param]["description"] = node_interface["parameters"][node_param]["description"]
+        else:
+            print(f"Adding missing parameter: {node_param}")
+            doc_interface["parameters"][node_param] = node_interface["parameters"][node_param]
+
+    # Check if subscriber names are the same
+    for node_sub in node_interface["subscribers"]:
+        if node_sub in doc_interface["subscribers"]:
+            # Update type if different
+            if node_interface["subscribers"][node_sub]["type"] != doc_interface["subscribers"][node_sub]["type"]:
+                print(f"Updating subscriber type for {node_sub}")
+                doc_interface["subscribers"][node_sub]["type"] = node_interface["subscribers"][node_sub]["type"]
+            # Update description if different and not TODO
+            if node_interface["subscribers"][node_sub]["description"] != doc_interface["subscribers"][node_sub]["description"] and node_interface["subscribers"][node_sub]["description"] != TODO:
+                print(f"Updating subscriber description for {node_sub}")
+                doc_interface["subscribers"][node_sub]["description"] = node_interface["subscribers"][node_sub]["description"]
+        else:
+            print(f"Adding missing subscriber: {node_sub}")
+            doc_interface["subscribers"][node_sub] = node_interface["subscribers"][node_sub]
+
+    # Check if publisher names are the same
+    for node_pub in node_interface["publishers"]:
+        if node_pub in doc_interface["publishers"]:
+            # Update type if different
+            if node_interface["publishers"][node_pub]["type"] != doc_interface["publishers"][node_pub]["type"]:
+                print(f"Updating publisher type for {node_pub}")
+                doc_interface["publishers"][node_pub]["type"] = node_interface["publishers"][node_pub]["type"]
+            # Update description if different and not TODO
+            if node_interface["publishers"][node_pub]["description"] != doc_interface["publishers"][node_pub]["description"] and node_interface["publishers"][node_pub]["description"] != TODO:
+                print(f"Updating publisher description for {node_pub}")
+                doc_interface["publishers"][node_pub]["description"] = node_interface["publishers"][node_pub]["description"]
+        else:
+            print(f"Adding missing publisher: {node_pub}")
+            doc_interface["publishers"][node_pub] = node_interface["publishers"][node_pub]
+
+    # Check if service names are the same
+    for node_srv in node_interface["services"]:
+        if node_srv in doc_interface["services"]:
+            # Update type if different
+            if node_interface["services"][node_srv]["type"] != doc_interface["services"][node_srv]["type"]:
+                print(f"Updating service type for {node_srv}")
+                doc_interface["services"][node_srv]["type"] = node_interface["services"][node_srv]["type"]
+            # Update description if different and not TODO
+            if node_interface["services"][node_srv]["description"] != doc_interface["services"][node_srv]["description"] and node_interface["services"][node_srv]["description"] != TODO:
+                print(f"Updating service description for {node_srv}")
+                doc_interface["services"][node_srv]["description"] = node_interface["services"][node_srv]["description"]
+        else:
+            print(f"Adding missing service: {node_srv}")
+            doc_interface["services"][node_srv] = node_interface["services"][node_srv]
+
+    # Check if action names are the same
+    for node_action in node_interface["actions"]:
+        if node_action in doc_interface["actions"]:
+            # Update type if different
+            if node_interface["actions"][node_action]["type"] != doc_interface["actions"][node_action]["type"]:
+                print(f"Updating action type for {node_action}")
+                doc_interface["actions"][node_action]["type"] = node_interface["actions"][node_action]["type"]
+            # Update description if different and not TODO
+            if node_interface["actions"][node_action]["description"] != doc_interface["actions"][node_action]["description"] and node_interface["actions"][node_action]["description"] != TODO:
+                print(f"Updating action description for {node_action}")
+                doc_interface["actions"][node_action]["description"] = node_interface["actions"][node_action]["description"]
+        else:
+            print(f"Adding missing action: {node_action}")
+            doc_interface["actions"][node_action] = node_interface["actions"][node_action]
+    
+    # Now that we added all missing elements,
+    # check if there are any elements in the doc that are not in the node
+    for doc_param in doc_interface["parameters"].copy():
+        if doc_param not in node_interface["parameters"]:
+            print(f"Removing parameter: {doc_param}")
+            del doc_interface["parameters"][doc_param]
+    for doc_sub in doc_interface["subscribers"].copy():
+        if doc_sub not in node_interface["subscribers"]:
+            print(f"Removing subscriber: {doc_sub}")
+            del doc_interface["subscribers"][doc_sub]
+    for doc_pub in doc_interface["publishers"].copy():
+        if doc_pub not in node_interface["publishers"]:
+            print(f"Removing publisher: {doc_pub}")
+            del doc_interface["publishers"][doc_pub]
+    for doc_srv in doc_interface["services"].copy():
+        if doc_srv not in node_interface["services"]:
+            print(f"Removing service: {doc_srv}")
+            del doc_interface["services"][doc_srv]
+    for doc_action in doc_interface["actions"].copy():
+        if doc_action not in node_interface["actions"]:
+            print(f"Removing action: {doc_action}")
+            del doc_interface["actions"][doc_action]
+    
+    # Write to the document
+    # TODO: remove the old documentation and write a new one
+    writer = DocWriter(None, node_name, doc_interface)
+    writer.write(file_path)
+
+
diff --git a/ros2autodoc/verb/update.py b/ros2autodoc/verb/update.py
@@ -0,0 +1,34 @@
+from os.path import isfile
+
+from ros2cli.node.strategy import NodeStrategy
+from ros2cli.verb import VerbExtension
+
+from ros2autodoc.api import check_for_node, update_documentation
+
+
+class UpdateVerb(VerbExtension):
+    """Update the documentation of a ROS2 node."""
+
+    def add_arguments(self, parser, cli_name):
+        parser.add_argument(
+            "nodes",
+            metavar="node",
+            nargs="*",
+            help="name of the nodes to be documented. If not specified, "
+            "all running nodes from the package will be documented.",
+        )
+        parser.add_argument(
+            "input_file",
+            help="absolute path of the README.md file to be updated.",
+        )
+
+    def main(self, *, args):
+        if not isfile(args.input_file):
+            return f"File: '{args.input_file}' could not be found."
+
+        with NodeStrategy(args) as node:
+            for node_name in args.nodes:
+                if not check_for_node(node, f"/{node_name}"):
+                    print(f"Node '{node_name}' is not running and will be ignored.")
+                    continue
+                update_documentation(node, node_name, args.input_file)
diff --git a/setup.py b/setup.py
@@ -4,7 +4,7 @@
 
 setup(
     name=PACKAGE_NAME,
-    version="2.1.2",
+    version="2.2.0",
     packages=find_packages(exclude=["test"]),
     data_files=[
         ("share/" + PACKAGE_NAME, ["package.xml"]),
@@ -32,6 +32,7 @@
         ],
         "ros2autodoc.verb": [
             "generate =  ros2autodoc.verb.generate:GenerateVerb",
+            "update = ros2autodoc.verb.update:UpdateVerb",
             "check = ros2autodoc.verb.check:CheckVerb",
         ],
     },
