docs: Reorganize documentation according to Diátaxis framework

Author: arounamounchili

docs/source/ARCHITECTURE.md docs/source/explanation/ARCHITECTURE.mddocs/source/ARCHITECTURE.md renamed to docs/source/explanation/ARCHITECTURE.md

@@ -0,0 +1,16 @@
+# Explanation: The LinkForge Data Model
+
+To understand how LinkForge converts a Blender scene into a URDF, it's important to understand the underlying data model.
+
+## Why not just use Blender groups?
+Standard Blender parent-child relationships don't store enough information for robotics simulation (like joint types, axis orientations, or mass properties).
+
+## The Three Layers
+LinkForge maintains a parallel data structure that maps Blender objects to URDF elements:
+
+1. **Blender Object Layer**: The visual mesh and collision geometry you see in the viewport.
+2. **LinkForge Property Layer**: Hidden custom properties attached to Blender objects that store mass, inertia, and joint settings.
+3. **Core URDF Model**: An immutable Python object created only during validation/export that ensures the robot tree is mathematically sound.
+
+## Coordinate Frames
+Blender uses a **Right-Handed Z-Up** coordinate system. LinkForge ensures that when you export to URDF (which is also Right-Handed), all offsets and rotations are correctly converted so your robot "stands up" correctly in Gazebo.

docs/source/explanation/data_model.md

@@ -0,0 +1,10 @@
+# Explanation
+
+Explanation is **understanding-oriented**. It provides background, context, and deep dives into the "why" and "how" behind LinkForge's design.
+
+```{toctree}
+:maxdepth: 1
+
+ARCHITECTURE
+data_model
+```

docs/source/explanation/index.md

@@ -0,0 +1,28 @@
+# How-to: Add Sensors to Your Robot
+
+This guide shows you how to integrate sensors like LiDAR, Cameras, and IMUs into your LinkForge robot model for simulation.
+
+## Prerequisites
+- A robot model with at least one **Link** created.
+
+## 1. Prepare the Sensor Link
+A sensor in URDF is usually attached to a specific link. You can either attach it to an existing link (like `base_link`) or create a dedicated small mesh to represent the sensor body.
+
+## 2. Attaching the Sensor
+1. Select the link that should hold the sensor in the 3D Viewport.
+2. Open the **LinkForge** panel and navigate to the **Sensors** tab.
+3. Click **Add Sensor**.
+
+## 3. Configuration
+Once added, you can configure the sensor properties:
+- **Update Rate**: How many times per second the sensor scans (e.g., 30Hz).
+- **Topics**: The ROS topic name where data will be published.
+- **Noise Models**: Add Gaussian noise to simulate real-world sensor inaccuracies.
+
+### Common Sensor Types:
+- **LiDAR**: Requires `<ray>` configuration for samples and range.
+- **Camera**: Requires resolution and focal length settings.
+- **IMU**: Provides orientation and acceleration data.
+
+## 4. Gazebo Integration
+LinkForge automatically generates the necessary `<gazebo>` tags and plugins to make these sensors work instantly in **Gazebo Sim** or **Gazebo Classic**.

docs/source/getting_started.md

@@ -0,0 +1,9 @@
+# How-to Guides
+
+How-to guides are **task-oriented**. They provide specific "recipes" to help you solve a particular problem or complete a specific task.
+
+```{toctree}
+:maxdepth: 1
+
+add_sensors
+```

docs/source/how_to/add_sensors.md

@@ -1,93 +1,95 @@
 # LinkForge Documentation
 
-Welcome to LinkForge's documentation!
+Welcome to the official LinkForge documentation. LinkForge is a professional Blender extension designed to bridge the gap between 3D modeling and robotics simulation.
 
-**LinkForge** is a professional Blender extension for roboticists.
+Following the **Diátaxis framework**, our documentation is organized into four sections to help you find exactly what you need.
 
-**In robotics, creativity starts in your head — but getting that idea into a simulator usually means hours of writing XML, fixing joint limits, and fighting coordinate systems.**
+---
 
-LinkForge removes that friction. Model your robot in Blender as naturally as sculpting a 3D scene, then let LinkForge handle the engineering.
+::::{grid} 2
+:gutter: 3
 
-**From idea → robot → ready for simulation.** All inside Blender.
+:::{grid-item-card} 🚀 Tutorials
+:link: tutorials/index
+:link-type: doc
 
-```{toctree}
-:maxdepth: 2
-:caption: Contents:
-
-getting_started
-ARCHITECTURE
-api/index
-CONTRIBUTING
-CHANGELOG
-README
-LICENSE
-```
-
-## Quick Links
+**Learning-oriented.** Start here if you are new to LinkForge. Step-by-step lessons to build your first robot.
+^^^
+- [Building a Diff-Drive Robot](tutorials/building_diff_drive)
+:::
 
-- [GitHub Repository](https://github.com/arounamounchili/linkforge)
-- [Issue Tracker](https://github.com/arounamounchili/linkforge/issues)
-- [Discussions](https://github.com/arounamounchili/linkforge/discussions)
+:::{grid-item-card} 🛠️ How-to Guides
+:link: how_to/index
+:link-type: doc
 
-## Features
+**Task-oriented.** Practical guides to help you achieve specific goals or solve problems.
+^^^
+- [Adding Sensors](how_to/add_sensors)
+- [Defining Joints](how_to/index)
+:::
 
-- **Bidirectional Workflow**: Seamlessly import existing URDF/XACRO files for editing or build complex robot models from scratch using Blender's native tools.
-- **Production-Ready Export**: Generates strictly compliant URDF/XACRO files optimized for ROS, ROS 2, and Gazebo. Output is clean, validated, and requires no manual post-processing.
-- **Smart Validation**: Built-in integrity checker inspects robot topology, physics data, and joint limits to prevent common simulation crashes before they happen.
-- **ROS2 Control Support**: Automatically generates hardware interface configurations for `ros2_control`, compatible with Gazebo, Webots, Isaac Sim, and physical hardware.
-- **Complete Sensor Suite**: Integrated support for Camera, Depth Camera, LiDAR, IMU, GPS, and Force/Torque sensors with configurable noise models.
-- **Automatic Physics**: Scientifically accurate calculation of mass properties and inertia tensors for both primitive shapes and complex arbitrary meshes.
-- **Advanced XACRO Support**: Intelligent extraction of repeated geometry into macros and shared materials, producing maintainable and modular code.
-- **Round-Trip Fidelity**: Import → Edit → Export cycle preserves all data absolute precision, including sensor origins, transmission interfaces, and custom user properties.
-- **Interactive Kinematic Visualization**: Real-time rendering of joint coordinate frames (`RGB=XYZ`) in the viewport, enabling instant visual verification of kinematic chain orientations.
+:::{grid-item-card} 💡 Explanation
+:link: explanation/index
+:link-type: doc
 
+**Understanding-oriented.** Deep dives into the architecture, theory, and design of LinkForge.
+^^^
+- [Architecture Guide](explanation/ARCHITECTURE)
+- [Data Model](explanation/data_model)
+:::
 
-## 🛠️ Workflow
+:::{grid-item-card} 📚 Reference
+:link: reference/index
+:link-type: doc
 
-LinkForge follows a structured **Forge → Perceive → Control → Export** workflow:
+**Information-oriented.** Technical descriptions, API documentation, and specifications.
+^^^
+- [Python API Reference](reference/api/index)
+- [URDF Specification](reference/index)
+:::
 
-### 1. Forge Links
-- Convert meshes to robot links with automatic naming
-- Generate optimized collision geometry
-- Calculate physics properties (mass, inertia)
-- Reversible actions (safely remove links)
+::::
 
-### 2. Forge Joints
-- Connect links with precise joint configuration
-- Visual feedback for joint axes in viewport
-- Full CRUD operations (Create, Read, Update, Delete)
-- Support for all URDF joint types
+---
 
-### 3. Perceive (Sensors)
-- Attach sensors to links
-- Configure update rates, resolutions, noise models
-- Gazebo plugin integration
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Tutorials
 
-### 4. Control (Transmissions)
-- Configure hardware interfaces (Position, Velocity, Effort)
-- Set up mechanical reductions and joint limits
-- Auto-generate `ros2_control` tags
+tutorials/building_diff_drive
+```
 
-### 5. Validate & Export
-- Built-in validator catches common errors
-- Export to URDF or XACRO with mesh handling
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: How-to Guides
 
-## Installation
+how_to/add_sensors
+```
 
-### Requirements
-- Blender 4.2 or later
-- Python 3.11+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Explanation
 
-### Installation
+explanation/ARCHITECTURE
+explanation/data_model
+```
 
-1. **Download**: Get `linkforge-1.0.0.zip` from [Releases](https://github.com/arounamounchili/linkforge/releases).
-2. **Open Blender**: Go to **Edit > Preferences > Get Extensions**.
-3. **Install**: Click the dropdown (⌄) in top-right → **Install from Disk**.
-4. **Select**: Choose the downloaded `.zip` file.
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Reference
 
+reference/api/index
+CHANGELOG
+CONTRIBUTING
+LICENSE
+```
 
-## Indices and tables
+## Quick Links
 
-- {ref}`genindex`
-- {ref}`modindex`
-- {ref}`search`
+- [GitHub Repository](https://github.com/arounamounchili/linkforge)
+- [Issue Tracker](https://github.com/arounamounchili/linkforge/issues)
+- [Discussions](https://github.com/arounamounchili/linkforge/discussions)