看，这就是 Documentinator！

Documentinator（又称docTor或doctor）是一个 Ros2 文档生成器。它通过使用预定义和强制的配置文件，生成常见的节点文档，以便简化文档风格管理和复制。

要安装 doctor，首先 安装 Rust，然后运行：cargo install documentinator。现在 doctor 应该已经添加到您的路径中了。只需再次运行此命令即可更新。

待办事项

doctor 目前可用于文档生成，但仅限于此。此外，它还不能默认以 doctor 的形式调用。

• 创建初始化
• 创建生成器
• 别名 doctor
• 添加 mdbook 生成支持
• 改善 CI 体验
• 整理和编写文档

docTor 有 3 个命令

doctor init - 创建示例 TOML

doctor gen - 生成文档

生成

doctor 通过在传递的目录中搜索配置文件来生成文件。如果传递了 -r，它也会递归。

每个配置将为每个节点生成文档。可以使用 --readme 生成指向所有生成节点文档的 readme.md，这在 CI 动作中生成 GitHub 仓库的 readmes 时非常有用。

配置

文档将在 nodename.doctor.toml 文件中。每个 toml 可以有 n 个节点，或者每个节点可以有自己的文件。

示例 Toml 文件

package_name = "white line detection"
repo = "https://github.com/iscumd/white_line_detection"

[[nodes]]
node_name = 'White_line_detection'
source_file = ['/src/white_line_detection.cpp']
summary = '''
This node allows Ohm to avoid the bounding white lines by consuming images published on the image_raw topic and publishing found white lines as point clouds.
This is currently achived using OpenCv, and a small algortithm. The node operates in a pull fashion, only computing when an image is published.
When an image is published, the node converts the image to an OpenCv Umat, then perspective shifting the image, then filtering out 'non-white' pixels,
and finally determining where the remaining pixels are in relation to the robot, and publishing that point as a pointcloud/PC2 to both 'camera_cloud' and 'camera_cloud2'.
Ohm will then see these points as a wall, preventing it from crossing.
'''
potential_improvements = 'Burn with fire'
misc = 'An (optional) description of something else.'

[[nodes.publishes]]
name = 'camera_cloud'
description = 'Ohm spesific pointcloud topic.'

[[nodes.publishes]]
name = 'camera_cloud2'
description = 'Ohm spesific pointcloud2d topic.'

[[nodes.subscribes]]
name = 'image_raw'
description = 'The raw image (not-debayerd) from the camera node/gazebo.'

[[nodes.subscribes]]
name = 'camera_info'
description = 'The standard camera info topic, used to find things like resolution.'

[[nodes.params]]
name = 'kernel_size'
description = 'Size of the erosion kernel. Default 5'

[[nodes.launch]]
file_path = '/launch/WLD.launch.py'
usage = 'just launch I guess'

[[nodes.launch.remap]]
from = 'camera_cloud'
to = 'foo_cloud'

[[nodes.launch.args]]
name = 'arg1'
description = 'Some arg to the launchfile'

[[nodes.launch.args]]
name = 'arg2'
description = 'Another arg to the launchfile'

TOML 格式

配置文件具有以下有效结构。

注意：标记为 '可选' 的标签可以在 toml 中省略。

• package_name: 字符串
• repo: 字符串
• nodes: 字符串数组
  • node_name: 字符串
  • source_file: 字符串数组
  • summary: 字符串
  • potential_improvements: 可选字符串
  • misc: 可选字符串
  • publishes: 可选字符串数组
    • name: 字符串
    • description: 字符串
  • subscribes: 可选字符串数组
    • name: 字符串
    • description: 字符串
  • params: 可选字符串数组
    • name: 字符串
    • description: 字符串
  • launch: 可选字符串数组
    • file_path: 字符串
    • usage：字符串
    • args：可选的数组
      • name: 字符串
      • description: 字符串
    • remap：可选的数组
      • from：字符串
      • to：字符串

使用示例

为名为 'node_name' 的节点创建示例配置

documentinator init node_name

生成当前目录中所有配置的 markdown 文件

documentinator gen.

生成当前目录及其所有子目录中所有配置的 markdown 文件

documentinator gen-r.

生成一个 markdown 读取说明，链接到所有其他生成的节点文档（并生成它们）

documentinator gen--readme.