Merge NoDL efforts with rosdoc2/rosindex efforts to automatically document nodes

[rkent]

I've been working for the last few weeks on an effort to use ai to automatically generate node documentation, with the goal to include this in rosdoc2 as a .md file with node descriptions, and in rosindex as a searchable list of available nodes in a rosdistro.

There is a lot of overlap in my efforts and the NoDL efforts. My efforts, being focused on ai generation, tend toward methods that are typically used in the ai world. I'm using JSON schema language to describe the node description. Some of my needs include:

• parameters need a text description, which ai uses to decide what a parameter is.
• nodes have both a short and long description. A short description is useful in a table in rosindex of all nodes. A long description is useful in rosdoc2 in a webpage that give a full description of the node.

My current work is at https://github.com/rkent/ai-nodedoc although this is not currently intended to be a puclic presentation of the work. The current format of a node schema from that repo:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/rkent/ai-rosdoc/ai-instructions/node-doc.schema.json",
  "title": "ROS 2 Node Documentation",
  "type": "object",
  "required": ["donotmodify", "name", "summary", "overview", "repo", "package", "parameters", "interfaces", "examples"],
  "additionalProperties": false,
  "properties": {
    "donotmodify": { "type": "boolean", "default": false, "description": "This field is used to indicate that the JSON file should not be changed by an AI agent, as it has been manually modified."},
    "name":        { "type": "string", "description": "The name of the ROS 2 node, e.g 'talker'" },
    "summary":     { "type": "string", "minLength": 30, "maxLength": 100, "description": "A concise summary of the node's functionality." },
    "overview":    { "type": "string", "minLength": 110, "maxLength": 600, "description": "A longer description of the node's functionality"},
    "repo":        { "type": "string", "description": "The path to the repository where the node's source code is located." },
    "package":     { "type": "string", "description": "The name of the ROS 2 package containing the node." },
    "parameters": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "type", "default", "summary"],
        "additionalProperties": false,
        "properties": {
          "name":    { "type": "string" },
          "type":    { "type": "string" },
          "default": { "type": "string" },
          "summary": { "type": "string", "minLength": 30, "maxLength": 100 }
        }
      }
    },
    "interfaces": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["itype", "topic", "mtype", "summary"],
        "additionalProperties": false,
        "properties": {
          "itype": {
            "type": "string",
            "description": "The type of interface, which can be one of the following: 'publisher', 'subscriber', 'service', 'client', 'action server', or 'action client'.",
            "enum": ["publisher", "subscriber", "service", "client", "action server", "action client"]
          },
          "topic":   { "type": "string", "description": "The name of the topic, service, or action." },
          "mtype":   { "type": "string", "description": "The message type used by the interface." },
          "summary": { "type": "string", "minLength": 30, "maxLength": 100, "description": "A concise summary of the interface's functionality." }
        }
      }
    },
    "examples": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "type": "string",
        "description": "example of how to run the node using the `ros2 run` command."
      }
    }
  }
}

My overall implementation plan would be to include the generation of the node description .json file as part of rosdoc2 processing of a package. rosindex would read the .json files from the rosdoc2-generated package API documentation, and use it to prepare a distro-wide index of available nodes. An early demo of this is available at https://ai-index.rosdabbler.com/search_nodes/ with discussion at https://openrobotics.zulipchat.com/#narrow/channel/526027-ROS-General/topic/demo.20of.20ai.20generated.20index.20of.20ros.20nodes.20and.20interfaces/with/577342596

[emersonknapp]

Love it - automatic documentation generation is a key part of the roadmap for this project!

#50 is tracking work toward a schema, which should provide most if not all of the info needed to produce documentation. We're targeting allowing for YAML&XML NoDL specs - which could be JSON since all JSON is valid YAML.

We've just gotten this repo transferred over to this org, I'm working on organizing the roadmap and tickets - if you're able to join us at the next meeting of the WG it'd be great to discuss your work and how we get it all together https://docs.google.com/document/d/1xFqQECOKVCR3sZIUHGCPUi2huXw6nvgMxu6G3qBuQDU/edit?usp=sharing - but we can also continue the conversation async.