Docs for Rust devs

docs/README.md

@@ -0,0 +1,19 @@
+# 📚 Documentation Guide
+
+Welcome to the documentation for this **up-rust**!  
+Follow the steps below to read the documents in the correct order:
+
+---
+
+## 🧭 Start Here
+
+1. **[Introduction.md](./../README.md)**  
+   → Overview of the project, purpose, and goals.
+
+2. **[Up-Spec](https://github.com/eclipse-uprotocol/up-spec/blob/main/README.adoc)**  
+   → Overview of the up-spec.
+3. **[Up-Spec](./up-spec.MD)**  
+   → Purpose and Installation of **up-spec** in **up-rust**.
+
+4. **[build file](./build.MD)**  
+   → Overview of the build file in the project.

docs/build.MD

@@ -0,0 +1,70 @@
+# 🏗️ Build Process
+
+## 📘 Overview
+
+The [`build.rs`](./../build.rs) file is a special build script that is executed automatically by Cargo during the following commands:
+
+- `cargo build`
+- `cargo test`
+- `cargo run`
+
+---
+
+## 🔁 Execution Flow
+
+```text
+cargo build / test / run
+        ⬇️
+Cargo checks for a build.rs file in the root directory
+        ⬇️
+If found, it runs the main() function inside build.rs
+        ⬇️
+Once build.rs finishes, Cargo proceeds with:
+   - Running main() if it's a binary (`bin`) package
+   - Running tests if it's a library (`lib`) package
+```
+
+## 🔧 What’s Inside `build.rs`
+
+The `build.rs` file is a Rust build script that runs **before** your crate is compiled.
+
+Here’s what it does at a high level:
+
+- ✅ **Specifies `.proto` files** that define the uProtocol data models (e.g., `uuid.proto`, `uri.proto`, `umessage.proto`, etc.)
+
+- ⚙️ **Uses `protobuf_codegen`** to generate Rust code from those `.proto` files
+
+- 📦 **Outputs** the generated code to the crate’s output directory (`OUT_DIR`)
+
+- 🔄 Uses a **vendored `protoc` compiler** (via `protoc-bin-vendored`) instead of relying on a system-installed version
+
+- 🧩 Conditionally includes optional features like:
+  - `udiscovery`
+  - `usubscription`
+  - `utwin`
+  - `cloudevents` (generates separately)
+
+This script ensures that whenever you build the crate, the Protobuf definitions are always up-to-date and compiled into Rust.
+
+---
+
+## 🧭 build.rs Execution Flow Diagram
+
+```bash
+cargo build / test / run
+        ⬇️
+Cargo looks for build.rs in the root directory
+        ⬇️
+If found, it executes build.rs
+        ⬇️
+build.rs:
+   - Lists .proto files to compile
+   - Sets up protoc compiler (vendored)
+   - Runs protobuf_codegen
+        ⬇️
+Protobuf Rust code is generated into:
+   📂 $OUT_DIR/uprotocol
+   📂 $OUT_DIR/cloudevents (if feature enabled)
+        ⬇️
+Rust code uses generated types at compile time
+```

docs/up-spec.MD

@@ -0,0 +1,67 @@
+# up-spec
+
+## 📘 Overview
+
+**`up-spec`** is the core specification repository of [uProtocol](https://github.com/eclipse-uprotocol/up-spec).  
+It defines the **Protobuf-based communication protocols** used by uProtocol across its layers.
+
+This repository is included as a submodule in the [up-rust](https://github.com/eclipse-uprotocol/up-rust/) project.
+
+---
+
+## 📦 What's Inside?
+
+The `up-spec` repository contains:
+
+- Protobuf message definitions.
+- Specification for all **three layers** of the uProtocol communication stack.
+- Core schema files that are shared across uProtocol implementations.
+
+---
+
+## ⬇️ How to Download
+
+There are two ways to get `up-spec`:
+
+---
+
+### ✅ Method 1: Clone with Submodules (Recommended)
+
+Download the **up-spec** with the **up-rust** in single command
+
+```bash
+# clone the up-rust repository
+git clone --recurse-submodules [email protected]:eclipse-uprotocol/up-rust
+```
+
+Here the submodule **up-spec** also downloaded in you can see it in parent location named **up-spec**.
+
+### 🔧 Method 2: Clone Without Submodules (Manual Setup)
+
+First Download the **up-rust** and then download the **up-spec** as submodule using the below command
+
+##### For ssh clone
+
+```bash
+# Clone the up-rust
+[email protected]:eclipse-uprotocol/up-rust.git
+
+# then run to download the submodules
+git submodule update --init --recursive
+```
+
+##### For Https clone
+
+```bash
+# Clone the up-rust
+https://github.com/eclipse-uprotocol/up-rust.git
+
+# Make sure to change the .gitmodules file in the up-rust folder
+# ./.gitmodules
+# url = [email protected]:eclipse-uprotocol/up-spec
+# To
+# url = https://github.com/eclipse-uprotocol/up-spec.git
+
+# Then update the submodule
+git submodule update --init --recursive
+```