docs: added existing documentation main repo

Author: juelg

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Build and Deploy Sphinx Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build Sphinx HTML
+        run: sphinx-build -b html docs docs/_build/html
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -19,3 +19,4 @@ settings.json
 *.egg-info
 video*
 GEMINI.md
+docs/_build

docs/_static/.keep

@@ -0,0 +1 @@
+# Changelog

docs/changelog.md

@@ -0,0 +1,48 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'Robot Control Stack'
+author = 'Tobias Jülg'
+release = '0.4'
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['_static']
+html_logo = "images/rcs_logo_multiline.svg"
+html_favicon = "images/favicon.ico"
+
+html_theme_options = {
+    "github_url": "https://github.com/RobotControlStack/robot-control-stack",
+    "use_edit_page_button": True,
+    "show_prev_next": False,
+    "navbar_start": ["navbar-logo"],  # ensures the logo is shown
+    "logo": {
+        "image_light": "images/rcs_logo_multiline.svg",  # your PNG
+        "image_dark": "images/rcs_logo_multiline.svg",   # can be same or a dark-mode version
+    },
+
+}
+
+html_context = {
+    "github_user": "RobotControlStack",
+    "github_repo": "robot-control-stack",
+    "github_version": "main",  # branch name
+    "doc_path": "docs",        # relative path in the repo where your docs live
+}
+
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "linkify",
+]

docs/conf.py

@@ -0,0 +1 @@
+# Contributing

docs/contributing.md

@@ -0,0 +1,9 @@
+# Documentation
+
+```{toctree}
+:maxdepth: 1
+documentation/getting_started.md
+documentation/usage.md
+documentation/hardware_extentions.md
+documentation/development.md
+```

docs/documentation.md

@@ -0,0 +1,24 @@
+# Development
+```shell
+# check for c++ formatting errors
+make cppcheckformat
+# fix them
+make cppformat
+# Linting with clang tidy
+make cpplint
+# check for python formatting errors
+make pycheckformat
+# fix them
+make pyformat
+# Linting with ruff and mypy
+make pylint
+# Testing
+make pytest
+```
+
+## Stub Files for Python Bindings
+We use autogenerated python stub files (`.pyi`) in the [`_core`](python/rcs/_core/) folder to show our linters the expected types of the C++ Python bindings.
+If the python bindings in the C++ code have changed you might need to regenerate them by using:
+```shell
+make stubgen
+```

docs/documentation/development.md

@@ -0,0 +1,10 @@
+# Getting Started
+
+```{toctree}
+:maxdepth: 1
+
+getting_started/installation.md
+getting_started/docker_installation.md
+getting_started/concepts.md
+
+```

docs/documentation/getting_started.md

@@ -0,0 +1,158 @@
+# Build System
+
+## 1. You Run
+
+    pip install -e .
+
+This tells `pip` to:
+
+- Perform an **editable install** of the current project.
+- Use the `pyproject.toml` as the **single source of truth** for building and packaging.
+
+---
+
+## 2. `pip` Reads `pyproject.toml`
+
+It sees:
+
+    [build-system]
+    build-backend = "scikit_build_core.build"
+
+So `pip` uses **`scikit-build-core`** as the **build backend** (instead of legacy `setuptools`).
+
+---
+
+## 3. `scikit-build-core` Invokes CMake
+
+It starts a CMake build, just like if you had run:
+
+    cmake -S . -B build
+    cmake --build build
+
+It uses the `CMakeLists.txt` at the project root, which:
+
+- Declares the project:
+  
+      project(rcs LANGUAGES C CXX VERSION 0.4.0)
+  
+- Sets modern C++20 and compiler policies.
+- Locates external dependencies:
+  - `Eigen3`, `Python3`, `MuJoCo`, `pinocchio`
+- Downloads with `FetchContent`: `rl`, `pybind11`
+- Includes:
+  
+      add_subdirectory(src)
+
+---
+
+## 4. CMake Enters `src/CMakeLists.txt`
+
+    add_subdirectory(rcs)
+    target_include_directories(rcs INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
+    add_subdirectory(sim)
+    add_subdirectory(pybind)
+
+This loads and builds 3 subcomponents.
+
+---
+
+## 5. Subcomponent Builds
+
+### `src/rcs/CMakeLists.txt`
+
+    add_library(rcs SHARED)
+    target_sources(rcs PRIVATE Pose.cpp Robot.cpp IK.cpp utils.cpp)
+    target_link_libraries(rcs PUBLIC Eigen3::Eigen mdl pinocchio::all)
+
+- Builds a **shared C++ library**: `rcs`
+- Contains your **robot control logic**
+- Exposes `include/` headers
+- Linked against external libraries
+
+### `src/sim/CMakeLists.txt`
+
+    add_library(sim)
+    target_sources(sim PRIVATE sim.cpp SimRobot.cpp ...)
+    target_link_libraries(sim PUBLIC rcs MuJoCo::MuJoCo)
+
+- Builds a **C++ simulation library**
+- Depends on:
+  - Your own `rcs` library
+  - MuJoCo physics engine
+
+### `src/pybind/CMakeLists.txt`
+
+    pybind11_add_module(_core MODULE rcs.cpp)
+    target_link_libraries(_core PRIVATE sim rcs)
+
+- Compiles a Python extension module: `_core.so`
+- Uses `pybind11` to bind C++ classes/functions
+- Links to both `sim` and `rcs` native libraries
+- Adds install instructions:
+  
+      install(TARGETS _core rcs DESTINATION rcs COMPONENT python_package)
+
+---
+
+## 6. Packaging into Python
+
+From `pyproject.toml`:
+
+    [tool.scikit-build]
+    build.targets = ["_core", "scenes", "rcs"]
+    wheel.packages = ["python/rcs"]
+    install.components = ["python_package"]
+
+- `scikit-build-core` installs `_core.so` into:
+  
+      python/rcs/_core.so
+  
+- That directory becomes a valid **Python package**
+
+---
+
+## 7. Result: Python Import Works
+
+After install:
+
+    from rcs import _core
+
+- You now access the C++ functionality exposed in `rcs.cpp` through Python.
+- `_core` contains Python-wrapped C++ objects/functions via `pybind11`.
+
+---
+
+## Summary Diagram
+
+    pip install -e .
+            │
+            ▼
+    Reads pyproject.toml (scikit_build_core used)
+            │
+            ▼
+    CMakeLists.txt (root) → add_subdirectory(src)
+            │
+            ▼
+    src/rcs → builds C++ library `rcs`
+    src/sim → builds C++ library `sim`
+    src/pybind → builds Python extension `_core`
+            │
+            ▼
+    All .so libraries installed in `python/rcs/`
+    `_core` accessible from Python as import
+
+---
+
+## Recap of Build Layers
+
+| Layer | Role | Tool |
+| --- | --- | --- |
+| `pyproject.toml` | Project metadata, build backend | `pip`, `scikit-build-core` |
+| `CMakeLists.txt` (root) | Configure the full C++ build | `CMake` |
+| `src/rcs` | Core robot logic in C++ | `C++`, `Eigen`, `pinocchio` |
+| `src/sim` | Simulation logic, MuJoCo | `C++`, `MuJoCo` |
+| `src/pybind` | Bindings to Python | `pybind11` |
+| `python/rcs/` | Python package with compiled `.so` | `scikit-build`, `pip` |
+
+
+