Skip to content

Commit

Permalink
Merge pull request #247 from clearpathrobotics/lcamero/development
Browse files Browse the repository at this point in the history 
Mermaid Diagrams
  • Loading branch information
@tonybaltovski
tonybaltovski authored Jun 3, 2024
2 parents 45fcdd4 + e80afd3 commit 3f86156
Show file tree
Hide file tree
Showing 5 changed files with 2,262 additions and 784 deletions.
110 changes: 110 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -374,3 +374,113 @@ Links to headings must not include an extra slash between the name of the page a
Finally, select _OK_, and _Save_

<img src="/static/img/readme_images/readme_solidworks_image_4.png" width="800"/>

## Mermaid Diagrams
Mermaid is a JavaScript based diagram generator that uses Markdown for descriptions and is available to docusaurus through a [plug-in](https://docusaurus.io/docs/next/markdown-features/diagrams).

To get started with Mermaid diagrams, use their [live tool](https://mermaid.live/edit). The live viewing tool is useful to explore the various diagrams using their readily available templates.
>> Currently, we are on version 2.4.3 of the Mermaid plug-in. Therefore, not all of the templates in the live version are available.
Although Mermaid is more complicated to use than other tools, it is easy to version and outputs HTML objects; the resulting diagrams can include links and the text within it is searchable. Additionally, HTML tags can be included within the diagrams for further customization. Refer to the [Mermaid Documentation](https://mermaid.js.org/intro/getting-started.html) for more details on the diagram descriptions.

### Themes
In the [Docusaurus configuration file](./docusaurus.config.js), we have defined the site-wide themes for the Mermaid diagrams. Mermaid offers a choice of five different themes to choose from. There is a way to call the `mermaidAPI` to set a customized site-wide theme, however, this has not yet been implemented.

See their [theming documentation](https://mermaid.js.org/config/theming.html) for more information.

### Creating a Diagram
In Docusaurus, we can use a [dyanmic Mermaid component](https://docusaurus.io/docs/next/markdown-features/diagrams#component) to define and load diagrams.

First, we import the dynamic component.
```
import Mermaid from '@theme/Mermaid';
```

Then, we instantiate the component with the graph passed in as an argument.
```
<Mermaid
value={`
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
`}
/>
```

### Configuring the Diagram
Diagrams can be modified indepent from the site-wide theme and configuration using [directives](https://mermaid.js.org/config/directives.html). Essentially, these directives are used to pass in an initialization configuration to the local diagram that overrides the existing global configuration.

For example, we can modify the way the arrow connecting two nodes is generated. Instead of the default, we can set the `curve` parameter to `step` to have the generated arrow move in steps rather than a smooth curve.
```
<Mermaid
value={`
%%{ \
init: { \
'flowchart': { \
'curve': 'step'
} \
} \
}%%
flowchart TD;
A-->B;
A-->C;
B-->D;
C-->D;
`}
/>
```

Notice that when defining a directive within the dynamic component, we must end every line with a backslash `\`. Make sure to not have any trailing commas, `,`, at the end of a list or dictionary.

See the [flowchart configuration](
https://mermaid.js.org/config/schema-docs/config-defs-flowchart-diagram-config.html) to see all the settings specific to flowcharts that can be modified with directives.

You may notice that there is no way to set the font size through the diagram's configuration. Instead that must be done by modifying the theme variables.
```
<Mermaid
value={`
%%{ \
init: { \
'themeVariables': { \
'fontSize': '16px'
} \
'flowchart': { \
'curve': 'step'
} \
} \
}%%
flowchart TD;
A-->B;
A-->C;
B-->D;
C-->D;
`}
/>
```
See the (Mermaid configuration)[https://mermaid.js.org/config/schema-docs/config.html] documentation page for an exhaustive list of parameters.


Even though the font size has been modified, the rendered diagram's font may not appear to change size. Instead, the text size will remain a relatively similar size while the boxes and arrows appear smaller. Therefore, the sure-fire method to set a font size is to use HTML `<font size=10></font>` tags to wrap the text within a node.
```
<Mermaid
value={`
%%{ \
init: { \
'themeVariables': { \
'fontSize': '16px'
} \
'flowchart': { \
'curve': 'step'
} \
} \
}%%
flowchart TD;
A-->B(<font size=10>B Text<font>);
A-->C;;
B-->D;
C-->D;
`}
/>
```
131 changes: 131 additions & 0 deletions docs_versioned_docs/version-ros2humble/ros/config/generators.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 4
---
import Mermaid from '@theme/Mermaid';

Part of the appeal of using the robot YAML configuration file is that it allows us to generate the necessary files
to operate the robot at runtime. There are 4 types of files that need to be generated: bash shell scripts, URDF description files,
Expand Down Expand Up @@ -38,6 +39,136 @@ The launch generator creates ROS 2 [python launch files](https://docs.ros.org/en

The parameter generator creates `.yaml` ROS parameter files that are used by the corresponding launch file. Each node has default parameters set that the user can overwrite by setting them in the robot configuration YAML.

### Platform Generation
By running the **bash**, **description**, **launch**, and **parameter** generators, the launch file and all necessary configuration files to run the platform nodes are created in the directory **/etc/clearpath/platform**. The top level launch file to start all platform related nodes is the **platform-service.launch.py**, which is generated in the **/etc/clearpath/platform/launch** directory by the **launch** generator. Each Clearpath platform robot has its own configuration files, but ultimately all parameter files generated in the same directory and the launch procedure is the same for every platform.

<Mermaid
value={`
%%{ \
init: { \
'themeVariables': { \
'fontSize': '16px' \
}, \
'flowchart': { \
'curve': 'stepAfter', \
'rankSpacing': 20 , \
'nodeSpacing': 50, \
'diagramPadding': 0 \
} \
} \
}%%
flowchart LR
%% Robot Yaml
yaml(((robot.yaml)))
%% Generators
g_bash{{<a href='https://github.com/clearpathrobotics/clearpath_common/blob/humble/clearpath_generator_common/clearpath_generator_common/bash/generator.py'><b>Bash Generator</b></a>}}
g_urdf{{<a href='https://github.com/clearpathrobotics/clearpath_common/blob/humble/clearpath_generator_common/clearpath_generator_common/description/generator.py'><b>Description Generator</b></a>}}
g_launch{{<a href='https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_generator_robot/clearpath_generator_robot/launch/generator.py'><b>Launch Generator</b></a>}}
g_param{{<a href='https://github.com/clearpathrobotics/clearpath_common/blob/humble/clearpath_generator_common/clearpath_generator_common/param/generator.py'><b>Parameter Generator</b></a>}}
%% Generated Files
bash([<div><b>setup.bash</b></div><div>/etc/clearpath/setup.bash</div>])
urdf([<div><b>robot.urdf.xacro</b></div><div>/etc/clearpath/robot.urdf.xacro</div>])
launch[[<div><b>platform-service.launch.py</b></div><div>/etc/clearpath/platform/launch/platform-service.launch.py</div>]]
control([<div><b>control.yaml</b></div><div>/etc/clearpath/platform/config/control.yaml</div>])
localization([<div><b>localization.yaml</b></div><div>/etc/clearpath/platform/config/localization.yaml</div>])
subgraph Clearpath Generators
yaml-.-g_bash
yaml-.-g_urdf
yaml-.-g_launch
yaml-.-g_param
end
g_bash-->bash
g_urdf-->urdf
g_launch-->launch
g_param-->control
g_param-->localization
subgraph Clearpath Platform Service
bash-.->launch
urdf-.->launch
control-.->launch
localization-.->launch
end
classDef generator stroke-width:4px
class g_bash generator
class g_urdf generator
class g_param generator
class g_launch generator
`}
/>

### Sensors Generation
Using the **parameter** and **launch** file generators, a pair of files is created for each sensor defined in the configuration file. Each sensor is enumerated given its order in sensor section of the **robot.yaml**. For example, if two cameras are added, then the first will be named **camera_0** and the second **camera_1**, irrespective of the model of camera. Each sensor launch file generated is included in the top level **sensors-service.launch.py** which is ran by the service.
<Mermaid
value={`
%%{ \
init: { \
'themeVariables': { \
'fontSize': '16px' \
}, \
'flowchart': { \
'curve': 'stepAfter', \
'rankSpacing': 20 , \
'nodeSpacing': 50, \
'diagramPadding': 0 \
} \
} \
}%%
flowchart LR
%% Robot Yaml
yaml(((robot.yaml)))
%% Generators
g_launch{{<a href='https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_generator_robot/clearpath_generator_robot/launch/generator.py'><b>Launch Generator</b></a>}}
g_param{{<a href='https://github.com/clearpathrobotics/clearpath_common/blob/humble/clearpath_generator_common/clearpath_generator_common/param/generator.py'><b>Parameter Generator</b></a>}}
%% Generated Launch Files
sensor_launch[[<div><b>sensor-service.launch.py</b></div><div>/etc/clearpath/sensors/launch/sensors-service.launch.py</div>]]
camera_launch[[<div><b>camera_0.launch.py</b></div><div>/etc/clearpath/sensors/launch/camera_0.launch.py</div>]]
gps_launch[[<div><b>gps_0.launch.py</b></div><div>/etc/clearpath/sensors/launch/gps_0.launch.py</div>]]
imu_launch[[<div><b>imu_0.launch.py</b></div><div>/etc/clearpath/sensors/launch/imu_0.launch.py</div>]]
lidar2d_launch[[<div><b>lidar2d_0.launch.py</b></div><div>/etc/clearpath/sensors/launch/lidar2d_0.launch.py</div>]]
lidar3d_launch[[<div><b>lidar3d_0.launch.py</b></div><div>/etc/clearpath/sensors/launch/lidar3d_0.launch.py</div>]]
extras_launch[[<div><i>extras</i><b>.launch.py</b></div><div>package://<i>extras_package</i>/<i>extras_path</i>/<i>extras</i>.launch.py</div>]]
%% Generated Parameter Files
camera_param([<div><b>camera_0.yaml</b></div><div>/etc/clearpath/sensors/config/camera_0.yaml</div>])
gps_param([<div><b>gps_0.yaml</b></div><div>/etc/clearpath/sensors/config/gps_0.yaml</div>])
imu_param([<div><b>imu_0.yaml</b></div><div>/etc/clearpath/sensors/config/imu_0.yaml</div>])
lidar2d_param([<div><b>lidar2d_0.yaml</b></div><div>/etc/clearpath/sensors/config/lidar2d_0.yaml</div>])
lidar3d_param([<div><b>lidar3d_0.yaml</b></div><div>/etc/clearpath/sensors/config/lidar3d_0.yaml</div>])
subgraph Clearpath Generators
yaml-.-g_launch
yaml-.-g_param
end
g_launch-->sensor_launch
g_launch-->camera_launch
g_launch-->gps_launch
g_launch-->imu_launch
g_launch-->lidar2d_launch
g_launch-->lidar3d_launch
g_param-->camera_param
g_param-->gps_param
g_param-->imu_param
g_param-->lidar2d_param
g_param-->lidar3d_param
subgraph Clearpath Sensors Service
camera_param-.-camera_launch
gps_param-.-gps_launch
imu_param-.-imu_launch
lidar2d_param-.-lidar2d_launch
lidar3d_param-.-lidar3d_launch
camera_launch-.-sensor_launch
gps_launch-.-sensor_launch
imu_launch-.-sensor_launch
lidar2d_launch-.-sensor_launch
lidar3d_launch-.-sensor_launch
extras_launch-.-sensor_launch
end
classDef generator stroke-width:4px
class g_bash generator
class g_urdf generator
class g_param generator
class g_launch generator
`}
/>

### Setup folder structure

Once all files are generated, the resulting setup folder structure under `/etc/clearpath/` will look like this:
Expand Down
12 changes: 11 additions & 1 deletion docusaurus.config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ const config = {
remarkPlugins: [math],
rehypePlugins: [katex],
showLastUpdateTime: true,
versions: {
versions: {
ros2humble: {
label: 'ROS 2 Humble',
},
Expand Down Expand Up @@ -80,6 +80,10 @@ const config = {
includeCurrentVersion: true,
},
],
[
"@docusaurus/theme-mermaid",
{}
],
],

themeConfig:
Expand Down Expand Up @@ -167,6 +171,12 @@ const config = {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
mermaid: {
theme: {light: "default", dark: 'dark'},
},
markdown: {
mermaid: true,
},
}),

stylesheets: [
Expand Down
Loading

0 comments on commit 3f86156

Please sign in to comment.