feat/add docstring format

.gitignore

@@ -1,5 +1,13 @@
 .temp/
 
+# CLAUDE
+.claudeignore
+CLAUDE.md
+
+# docs 
+docs/_build/
+docs/source/api/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to pySimBlocks
+
+Thank you for your interest in contributing to **pySimBlocks**.
+pySimBlocks is a research-oriented simulation framework for discrete-time
+block-diagram systems with a graphical editor and YAML project format.
+
+Contributions are welcome in the following areas:
+
+- Simulation engine
+- GUI editor
+- New blocks
+- Documentation
+- Tests
+- Performance improvements
+
+---
+
+## Repository architecture
+
+```
+.
+├── docs/               # User guides and block documentation
+├── examples/           # Usage examples
+├── pySimBlocks/
+│   ├── blocks/         # Block implementations (operators, controllers, sources, …)
+│   ├── core/           # Simulation engine (Model, Simulator, Block base class, …)
+│   ├── gui/            # PySide6 graphical editor
+│   ├── project/        # YAML project loading and code generation
+│   ├── real_time/      # Real-time execution
+│   └── tools/          # CLI and block registry utilities
+├── tests/              # Test suite
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Docstring format
+
+pySimBlocks uses **Google-style docstrings**. Every public class and method must
+have one.
+
+### Class
+
+```python
+class MyBlock(Block):
+    """One-line summary ending with a period.
+
+    Optional longer description: what the block computes, its mathematical
+    formulation, and any important behavioural notes.
+
+    Attributes:
+        gain: Scalar gain applied to the input.
+        sample_time: Sampling period, or None to use the global dt.
+    """
+```
+
+### Method
+
+```python
+def output_update(self, t: float, dt: float) -> None:
+    """Compute output y[k] = gain * u[k].
+
+    Args:
+        t: Current simulation time in seconds.
+        dt: Current time step in seconds.
+    """
+```
+
+**Rules:**
+- Always include `Args` when the method takes parameters beyond `self`.
+- Include `Returns` when the return value is not `None` and not obvious.
+- Include `Raises` for exceptions the caller should handle.
+- Do **not** repeat type information already present in the signature.
+- Private methods (`_foo`): a one-line comment is sufficient.
+
+---
+
+## Coding style
+
+Follow standard Python conventions:
+
+- Python ≥ 3.10
+- PEP 8 formatting
+- Descriptive variable names
+
+### Naming conventions
+
+| Element | Convention | Example |
+|---|---|---|
+| Block class | `PascalCase` | `DiscreteIntegrator`, `Gain` |
+| Block file | `snake_case` | `discrete_integrator.py`, `gain.py` |
+| GUI metadata class | `PascalCase` + `Meta` suffix | `DiscreteIntegratorMeta`, `GainMeta` |
+| GUI metadata file | same as block file | `discrete_integrator.py` |
+| Doc file | same as block file | `discrete_integrator.md` |
+| Test file | `test_` + block file | `test_discrete_integrator.py` |
+| Test functions | `test_<block>_<what>_<expected>` | `test_gain_negative_input_inverts_sign` |
+| Block `type` key (yaml/GUI) | `snake_case` | `"discrete_integrator"` |
+| Input/output port names | `snake_case` | `"in"`, `"out"`, `"error"` |
+| State keys | `snake_case` | `"x"`, `"x_i"`, `"prev_e"` |
+
+### Type hints
+
+Type hints are required for all methods and functions.
+
+All source files must include `from __future__ import annotations` as the
+first import to ensure correct rendering of type aliases (e.g. `ArrayLike`)
+in the Sphinx documentation.
+
+---
+
+## Running tests
+
+```bash
+pytest tests/
+```
+
+---
+
+© 2026 Université de Lille & INRIA
+Licensed under LGPL-3.0-or-later

README.md

@@ -17,7 +17,7 @@ using either:
 - YAML project configuration
 - Optional SOFA and hardware integration
 
-![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/gui_example.png)
+![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/gui_example.png)
 
 ## Features
 
@@ -103,7 +103,7 @@ plot_from_config(logs, plot_cfg)
 
 The resulting plot should look like this:
 
-![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/quick_example.png)
+![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/quick_example.png)
 
 See [examples/quick_start/filter.py](./examples/quick_start/filter.py)
 to run the example yourself.
@@ -127,13 +127,13 @@ The quick-start GUI project is stored in a single
 #### Tutorials
 
 Three step-by-step tutorials are available detailed in the
-[guide](./docs/User_Guide/getting_started.md):
+[guide](./docs/source/user_guide/tutorials.md):
 
   | | Tutorial | Description |
   |---|---|---|
-  | 1 | [Python API](./docs/User_Guide/tutorial_1_python.md) | Build a closed-loop PI control system in pure Python |
-  | 2 | [GUI](./docs/User_Guide/tutorial_2_gui.md) | Build the same system visually with the graphical editor |
-  | 3 | [SOFA](./docs/User_Guide/tutorial_3_sofa.md) | Replace the plant with a SOFA physics simulation |
+  | 1 | [Python API](./docs/source/user_guide/tutorials/tutorial_1_python.md) | Build a closed-loop PI control system in pure Python |
+  | 2 | [GUI](./docs/source/user_guide/tutorials/tutorial_2_gui.md) | Build the same system visually with the graphical editor |
+  | 3 | [SOFA](./docs/source/user_guide/tutorials/tutorial_3_sofa.md) | Replace the plant with a SOFA physics simulation |
 
 
 #### Other Examples

docs/Makefile

@@ -0,0 +1,11 @@
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR   = source
+BUILDDIR    = _build
+
+.PHONY: html clean
+
+html:
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+clean:
+	rm -rf $(BUILDDIR)