Add comprehensive Sphinx documentation structure and content

Co-authored-by: r41k0u <76248539+r41k0u@users.noreply.github.com>

docs/user-guide/index.md

@@ -0,0 +1,100 @@
+# User Guide
+
+This user guide provides comprehensive documentation for all PythonBPF features. Whether you're building simple tracing tools or complex performance monitoring systems, this guide will help you master PythonBPF.
+
+## Overview
+
+PythonBPF transforms Python code into eBPF bytecode that runs in the Linux kernel. It provides a Pythonic interface to eBPF features through decorators, type annotations, and familiar programming patterns.
+
+## Core Concepts
+
+### Decorators
+
+PythonBPF uses decorators to mark code for BPF compilation:
+
+* `@bpf` - Mark functions and classes for BPF compilation
+* `@map` - Define BPF maps for data storage
+* `@struct` - Define custom data structures
+* `@section(name)` - Specify attachment points
+* `@bpfglobal` - Define global variables
+
+### Compilation Pipeline
+
+Your Python code goes through several stages:
+
+1. **AST Parsing** - Python code is parsed into an Abstract Syntax Tree
+2. **IR Generation** - The AST is transformed into LLVM IR using llvmlite
+3. **BPF Compilation** - LLVM IR is compiled to BPF bytecode using `llc`
+4. **Loading** - The BPF object is loaded into the kernel using libbpf
+5. **Attachment** - Programs are attached to kernel hooks (tracepoints, kprobes, etc.)
+
+## Guide Contents
+
+```{toctree}
+:maxdepth: 2
+
+decorators
+maps
+structs
+compilation
+helpers
+```
+
+## Code Organization
+
+When writing BPF programs with PythonBPF, we recommend:
+
+1. **Keep BPF code in separate files** - Easier to manage and test
+2. **Use type hints** - Required for proper code generation
+3. **Follow naming conventions** - Use descriptive names for maps and functions
+4. **Document your code** - Add comments explaining BPF-specific logic
+5. **Test incrementally** - Verify each component works before adding complexity
+
+## Type System
+
+PythonBPF uses Python's `ctypes` module for type definitions:
+
+* `c_int8`, `c_int16`, `c_int32`, `c_int64` - Signed integers
+* `c_uint8`, `c_uint16`, `c_uint32`, `c_uint64` - Unsigned integers
+* `c_char`, `c_bool` - Characters and booleans
+* `c_void_p` - Void pointers
+* `str(N)` - Fixed-length strings (e.g., `str(16)` for 16-byte string)
+
+## Example Structure
+
+A typical PythonBPF program follows this structure:
+
+```python
+from pythonbpf import bpf, map, section, bpfglobal, BPF
+from pythonbpf.maps import HashMap
+from ctypes import c_void_p, c_int64, c_uint32
+
+# Define maps
+@bpf
+@map
+def my_map() -> HashMap:
+    return HashMap(key=c_uint32, value=c_uint64, max_entries=1024)
+
+# Define BPF function
+@bpf
+@section("tracepoint/...")
+def my_function(ctx: c_void_p) -> c_int64:
+    # BPF logic here
+    return c_int64(0)
+
+# License (required)
+@bpf
+@bpfglobal
+def LICENSE() -> str:
+    return "GPL"
+
+# Compile, load, and run
+if __name__ == "__main__":
+    b = BPF()
+    b.load_and_attach()
+    # Use the program...
+```
+
+## Next Steps
+
+Start with {doc}`decorators` to learn about all available decorators, then explore the other sections to master specific features.