docs(diagnostic_graph_aggregator): update documents

system/diagnostic_graph_aggregator/README.md

@@ -53,20 +53,27 @@ This feature breaks the generality of the graph and may be changed to a plugin o
 
 ## Examples
 
-- [example_0.yaml](./example/example_0.yaml)
-- [example_1.yaml](./example/example_1.yaml)
-- [example_2.yaml](./example/example_2.yaml)
+This is an example of a diagnostic graph configuration. The configuration can be split into multiple files.
+
+- [main.yaml](./example/graph/main.yaml)
+- [module1.yaml](./example/graph/module1.yaml)
+- [module2.yaml](./example/graph/module2.yaml)
+
+```bash
+ros2 launch diagnostic_graph_aggregator example-main.launch.xml
+```
+
+You can reuse the graph by making partial edits. For example, disable hardware checks for simulation.
+
+- [edit.yaml](./example/graph/edit.yaml)
 
 ```bash
-ros2 launch diagnostic_graph_aggregator example.launch.xml
+ros2 launch diagnostic_graph_aggregator example-edit.launch.xml
 ```
 
 ## Graph file format
 
-- [GraphFile](./doc/format/graph-file.md)
-- [Path](./doc/format/path.md)
-- [Node](./doc/format/node.md)
-  - [Diag](./doc/format/diag.md)
-  - [Unit](./doc/format/unit.md)
-  - [And](./doc/format/and.md)
-  - [Or](./doc/format/or.md)
+- [graph](./doc/format/graph.md)
+- [path](./doc/format/path.md)
+- [node](./doc/format/node.md)
+- [edit](./doc/format/edit.md)

system/diagnostic_graph_aggregator/doc/format/edit.md

@@ -0,0 +1,14 @@
+# Edit
+
+The `edit` is a base object that edits the existing diagnostic graph.
+Any derived object can be used where a edit object is required.
+
+## Format
+
+| Name   | Type     | Required | Description                                       |
+| ------ | -------- | -------- | ------------------------------------------------- |
+| `type` | `string` | yes      | The string indicating the type of derived object. |
+
+## Derived objects
+
+- [remove](./edit/remove.md)

system/diagnostic_graph_aggregator/doc/format/edit/remove.md

@@ -0,0 +1,10 @@
+# Remove
+
+The `remove` object is a edit that removes other nodes.
+
+## Format
+
+| Name   | Type     | Required | Description                              |
+| ------ | -------- | -------- | ---------------------------------------- |
+| `type` | `string` | yes      | Specify `remove` when using this object. |
+| `path` | `string` | yes      | The path of the node to remove.          |

system/diagnostic_graph_aggregator/doc/format/graph.md

@@ -0,0 +1,11 @@
+# Graph
+
+The graph object is the top level structure that makes up the configuration file.
+
+## Format
+
+| Name    | Type                                   | Required | Description                                       |
+| ------- | -------------------------------------- | -------- | ------------------------------------------------- |
+| `files` | <code>list\[[path](./path.md)\]</code> | no       | List of path objects for importing subgraphs.     |
+| `nodes` | <code>list\[[node](./node.md)\]</code> | no       | List of node objects that make up the graph.      |
+| `edits` | <code>list\[[edit](./edit.md)\]</code> | no       | List of edit objects to partially edit the graph. |

system/diagnostic_graph_aggregator/doc/format/node.md

@@ -1,9 +1,25 @@
 # Node
 
-Node is a base object that makes up the diagnostic graph.
+The `node` is a base object that makes up the diagnostic graph.
+Any derived object can be used where a node object is required.
 
 ## Format
 
-| Name | Type   | Required | Description                                 |
-| ---- | ------ | -------- | ------------------------------------------- |
-| type | string | yes      | Node type. See derived objects for details. |
+| Name   | Type     | Required | Description                                       |
+| ------ | -------- | -------- | ------------------------------------------------- |
+| `type` | `string` | yes      | The string indicating the type of derived object. |
+| `path` | `string` | no       | Any string to reference from other nodes.         |
+
+## Derived objects
+
+- [diag](./node/diag.md)
+- [and](./node/and.md)
+- [or](./node/or.md)
+- [remapping](./node/remap.md)
+  - warn-to-ok
+  - warn-to-error
+- [constant](./node/const.md)
+  - ok
+  - warn
+  - error
+  - stale

system/diagnostic_graph_aggregator/doc/format/node/and.md

@@ -0,0 +1,17 @@
+# And
+
+The `and` object is a node that is evaluated as the maximum error level of the input nodes.
+Note that error level `stale` is treated as `error`.
+
+## Format
+
+| Name   | Type                                   | Required | Description                                                  |
+| ------ | -------------------------------------- | -------- | ------------------------------------------------------------ |
+| `type` | <code>string</code>                    | yes      | Specify `and` or `short-circuit-and` when using this object. |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects.                                  |
+
+## Short-circuit evaluation
+
+!!! warning
+
+    The`short-circuit-and` is work in progress (WIP).

system/diagnostic_graph_aggregator/doc/format/node/const.md

@@ -0,0 +1,18 @@
+# Constant
+
+The constant object is a node with a fixed error level.
+
+## Format
+
+| Name   | Type     | Required | Description                                 |
+| ------ | -------- | -------- | ------------------------------------------- |
+| `type` | `string` | yes      | Specify error level when using this object. |
+
+## Error levels
+
+The supported error levels are as follows.
+
+- `ok`
+- `warn`
+- `error`
+- `stale`

system/diagnostic_graph_aggregator/doc/format/node/diag.md

@@ -0,0 +1,10 @@
+# Diag
+
+The `diag` object is a node that refers to a specific status within the source diagnostics.
+
+## Format
+
+| Name   | Type     | Required | Description                            |
+| ------ | -------- | -------- | -------------------------------------- |
+| `type` | `string` | yes      | Specify `diag` when using this object. |
+| `diag` | `string` | yes      | The name of the diagnostic status.     |

system/diagnostic_graph_aggregator/doc/format/node/link.md

@@ -0,0 +1,10 @@
+# Link
+
+The `link` object is a node that refers to other nodes.
+
+## Format
+
+| Name   | Type     | Required | Description                            |
+| ------ | -------- | -------- | -------------------------------------- |
+| `type` | `string` | yes      | Specify `link` when using this object. |
+| `link` | `string` | yes      | The path of the node to reference.     |

system/diagnostic_graph_aggregator/doc/format/node/or.md

@@ -0,0 +1,11 @@
+# Or
+
+The `or` object is a node that is evaluated as the minimum error level of the input nodes.
+Note that error level `stale` is treated as `error`.
+
+## Format
+
+| Name   | Type                                   | Required | Description                          |
+| ------ | -------------------------------------- | -------- | ------------------------------------ |
+| `type` | <code>string</code>                    | yes      | Specify `or` when using this object. |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects.          |

system/diagnostic_graph_aggregator/doc/format/node/remap.md

@@ -0,0 +1,21 @@
+# Constant
+
+!!! warning
+
+    This object is under development. It may be removed in the future.
+
+The remapping object is a node that converts error levels.
+
+## Format
+
+| Name   | Type                                   | Required | Description                                          |
+| ------ | -------------------------------------- | -------- | ---------------------------------------------------- |
+| `type` | `string`                               | yes      | Specify remapping type when using this object.       |
+| `list` | <code>list\[[node](../node.md)]</code> | yes      | List of input node objects. The list size must be 1. |
+
+## Remapping types
+
+The supported remapping types are as follows.
+
+- `warn-to-ok`
+- `warn-to-error`

system/diagnostic_graph_aggregator/doc/format/path.md

@@ -1,10 +1,19 @@
 # Path
 
-Path is an object that indicates the path of the file to include.
+The path object specifies the file path of the subgraph to be imported.
+The structure of the subgraph file should be [graph object](./graph.md).
 
 ## Format
 
-| Name    | Type   | Required | Description                   |
-| ------- | ------ | -------- | ----------------------------- |
-| package | string | yes      | Package name.                 |
-| path    | string | yes      | Relative path in the package. |
+| Name   | Type     | Required | Description                    |
+| ------ | -------- | -------- | ------------------------------ |
+| `path` | `string` | yes      | The file path of the subgraph. |
+
+## Substitutions
+
+File paths can contain substitutions like ROS 2 launch. The supported substitutions are as follows.
+
+| Substitution                  | Description                      |
+| ----------------------------- | -------------------------------- |
+| `$(dirname)`                  | The path of this file directory. |
+| `$(find-pkg-share <package>)` | The path of the package.         |

system/diagnostic_graph_aggregator/example/example.launch.xml → system/diagnostic_graph_aggregator/example/example-edit.launch.xml

@@ -1,7 +1,7 @@
 <launch>
   <include file="$(find-pkg-share diagnostic_graph_aggregator)/launch/diagnostic_graph_aggregator.launch.xml">
-    <arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/example_0.yaml"/>
+    <arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/graph/edit.yaml"/>
   </include>
   <node pkg="diagnostic_graph_aggregator" exec="converter" name="converter"/>
-  <executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/example_diags.py"/>
+  <executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/dummy-diags.py"/>
 </launch>

system/diagnostic_graph_aggregator/example/example-main.launch.xml

@@ -0,0 +1,7 @@
+<launch>
+  <include file="$(find-pkg-share diagnostic_graph_aggregator)/launch/diagnostic_graph_aggregator.launch.xml">
+    <arg name="graph_file" value="$(find-pkg-share diagnostic_graph_aggregator)/example/graph/main.yaml"/>
+  </include>
+  <node pkg="diagnostic_graph_aggregator" exec="converter" name="converter"/>
+  <executable cmd="python3 $(find-pkg-share diagnostic_graph_aggregator)/example/dummy-diags.py"/>
+</launch>

system/diagnostic_graph_aggregator/example/graph/edit.yaml

@@ -0,0 +1,6 @@
+files:
+  - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/graph/main.yaml }
+
+edits:
+  - path: /functions/obstacle_detection
+    type: remove

system/diagnostic_graph_aggregator/example/example_0.yaml → system/diagnostic_graph_aggregator/example/graph/main.yaml

@@ -1,6 +1,6 @@
 files:
-  - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_1.yaml }
-  - { path: $(find-pkg-share diagnostic_graph_aggregator)/example/example_2.yaml }
+  - { path: $(dirname)/module1.yaml }
+  - { path: $(dirname)/module2.yaml }
 
 nodes:
   - path: /autoware/modes/stop