ros-to-markdown

Convert ROS systems to Markdown for LLM processing.

Overview

ros-to-markdown is a Python tool that generates comprehensive Markdown documentation from ROS1 and ROS2 systems. It analyzes running ROS systems and generates documentation optimized for consumption by LLMs and AI agents.

Current Features

• Runtime System Analysis
  • Node discovery and relationships
  • Topic connections and message types
  • Basic system topology
• Markdown Generation
  • Mermaid diagrams for system visualization
  • Structured documentation
  • Namespace filtering
  • Node/topic filtering

Roadmap

• Performance Analysis
  • System metrics collection
  • Resource usage monitoring
  • Performance insights
  • Non-intrusive analysis
• Static Analysis
  • Package structure analysis
  • Source code documentation
  • Build configuration insights
• Historical Analysis
  • ROS bag file analysis
  • Performance trends
  • Pattern detection
• Advanced Features
  • Custom analysis perspectives
  • Plugin system
  • Interactive visualizations
  • Resource management

Installation

pip install ros-to-markdown

Usage

Run in your ROS workspace root:

# Basic system analysis
ros-to-markdown runtime

# Analyze specific namespace
ros-to-markdown runtime --namespace /robot1

# Filter specific nodes/topics
ros-to-markdown runtime --node-filter "camera*" --topic-filter "sensor_*"

# See all options
ros-to-markdown --help

Supported ROS Distributions

• ROS1: Noetic (EOL: May 2025)
• ROS2:
  • Humble LTS (EOL: May 2027)
  • Iron (EOL: Dec 2024)
  • Jazzy (EOL: May 2029)

Requirements

• Python ≥ 3.8
• ROS1 (Noetic) or ROS2 (Humble/Iron/Jazzy)
• Active ROS workspace

Documentation

Full documentation is available at readthedocs.

Project Status

Note

This repository started as an experiment to see how good current AI tools are at creating complex projects. The vast majority of code was generated by AI (Cursor with Claude 3.5 Sonnet), with almost no code written directly by the authors. That said, the authors did write the documentation and project structure, and spent a lot of time iterating with the AI to make it all work. Lessons learned will follow once the project nears completion.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

Apache 2.0 - See LICENSE for details.