Add first version of docs

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - 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 -e ".[docs,examples]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build --clean
+
+      - name: Setup Pages
+        if: github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -136,4 +136,7 @@ dmypy.json
 # DS_STORE
 .DS_Store
 *.mp4
-*.gif
+*.gif
+
+# Documentation build
+site/

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

Makefile

@@ -54,6 +54,23 @@ pytestcache-remove:
 build-remove:
 	rm -rf build/
 
+#* Documentation
+.PHONY: docs-serve
+docs-serve:
+	conda run --live-stream --name jsrm mkdocs serve
+
+.PHONY: docs-build
+docs-build:
+	conda run --live-stream --name jsrm mkdocs build --clean
+
+.PHONY: docs-build-strict
+docs-build-strict:
+	conda run --live-stream --name jsrm mkdocs build --clean --strict
+
+.PHONY: docs-deploy
+docs-deploy:
+	conda run --live-stream --name jsrm mkdocs gh-deploy --force
+
 .PHONY: cleanup
 cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove
 

README.md

@@ -1,5 +1,12 @@
 # JAX Soft Robot Modelling
 
+[![Test](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/test.yml/badge.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/test.yml)
+[![Documentation](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/docs.yml/badge.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/actions/workflows/docs.yml)
+[![PyPI version](https://badge.fury.io/py/jsrm.svg)](https://badge.fury.io/py/jsrm)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/github/license/tud-phi/jax-soft-robot-modeling.svg)](https://github.com/tud-phi/jax-soft-robot-modeling/blob/main/LICENSE.txt)
+[![Docs](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://tud-phi.github.io/jax-soft-robot-modelling)
+
 This repository contains symbolic derivations of the kinematics and dynamics of various soft robots using Sympy.
 The symbolic expressions are then implemented in JAX and can be used for fast, parallelizable, and differentiable simulations.
 So far, we have focused on planar settings and implemented the following soft robots:
@@ -68,6 +75,61 @@ Finally, we can simulate the pendulum
 python examples/simulate_pendulum.py
 ```
 
+## Documentation
+
+The full documentation is available at: https://tud-phi.github.io/jax-soft-robot-modelling
+
+### Building Documentation Locally
+
+To build and serve the documentation locally:
+
+```bash
+# Install documentation dependencies
+pip install -e ".[docs]"
+
+# Serve documentation with live reload (if mkdocs is in PATH)
+mkdocs serve
+
+# OR using conda environment
+conda run --live-stream --name jsrm mkdocs serve
+```
+
+The documentation will be available at `http://127.0.0.1:8000`.
+
+### Building Documentation for Production
+
+```bash
+# Build static documentation (if mkdocs is in PATH)
+mkdocs build
+
+# OR using conda environment
+conda run --live-stream --name jsrm mkdocs build
+
+# Build with strict mode (for CI/development)
+mkdocs build --strict
+# OR: conda run --live-stream --name jsrm mkdocs build --strict
+
+# Deploy to GitHub Pages (maintainers only)
+mkdocs gh-deploy
+# OR: conda run --live-stream --name jsrm mkdocs gh-deploy
+```
+
+You can also use the Makefile targets:
+
+```bash
+# Serve locally
+make docs-serve
+
+# Build documentation
+make docs-build
+
+# Build with strict mode checking
+make docs-build-strict
+
+# Deploy to GitHub Pages
+make docs-deploy
+```
+
 ## See also
 
 You might also be interested in the following repositories:

docs/404.md

@@ -0,0 +1,71 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# 🤖 404 - Page Not Found
+
+<div class="doc-summary">
+  <strong>Oops! The page you're looking for doesn't exist.</strong> But don't worry, we can help you get back on track with your soft robotics journey!
+</div>
+
+---
+
+## 🧭 Navigation Help
+
+<div class="feature-grid">
+  <div class="feature-card">
+    <h3><span class="icon">🏠</span> [Home](index.md)</h3>
+    <p>Go back to the main page and start fresh</p>
+  </div>
+
+  <div class="feature-card">
+    <h3><span class="icon">🚀</span> [Quick Start](user-guide/quick-start.md)</h3>
+    <p>Jump into hands-on tutorials and examples</p>
+  </div>
+
+  <div class="feature-card">
+    <h3><span class="icon">📚</span> [API Reference](api/systems.md)</h3>
+    <p>Browse the complete API documentation</p>
+  </div>
+
+  <div class="feature-card">
+    <h3><span class="icon">📖</span> [Examples](user-guide/examples.md)</h3>
+    <p>Explore comprehensive examples and use cases</p>
+  </div>
+</div>
+
+---
+
+## 🔍 Popular Resources
+
+!!! tip "Most Visited Pages"
+
+    - **[Installation Guide](installation.md)** - Get JSRM up and running
+    - **[Planar PCS Systems](api/planar-pcs.md)** - Continuum soft robot documentation  
+    - **[Contributing Guidelines](development/contributing.md)** - Join our community
+    - **[System Factory Pattern](user-guide/quick-start.md#core-concepts)** - Learn the basics
+
+---
+
+## 🆘 Still Lost?
+
+!!! question "Need help finding something specific?"
+
+    === "🔍 Search"
+        Use the search box at the top of the page to find what you're looking for.
+
+    === "📧 Contact"
+        Reach out to us at [[email protected]](mailto:[email protected])
+
+    === "🐛 Report Issue"
+        If you think this is a broken link, please [report it on GitHub](https://github.com/tud-phi/jax-soft-robot-modelling/issues/new)
+
+---
+
+<div style="text-align: center; margin: 2rem 0;">
+  <p style="font-size: 1.2rem; color: var(--md-primary-fg-color);">
+    🤖 <strong>Happy Coding with JSRM!</strong>
+  </p>
+</div>

docs/api/integration.md

@@ -0,0 +1,18 @@
+# Integration Utilities
+
+Numerical integration methods and utilities for solving differential equations.
+
+## Overview
+
+This module provides various integration schemes including Gauss-Legendre quadrature and other numerical methods used in the robot dynamics computations.
+
+## API Reference
+
+::: jsrm.integration
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/math-utils.md

@@ -0,0 +1,18 @@
+# Math Utilities
+
+Mathematical utility functions used throughout JSRM for various computations.
+
+## Overview
+
+This module provides core mathematical operations including linear algebra utilities, matrix operations, and specialized functions for robotics computations.
+
+## API Reference
+
+::: jsrm.math_utils
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/parameters.md

@@ -0,0 +1,18 @@
+# Parameters
+
+Parameter handling and configuration utilities for robot systems.
+
+## Overview
+
+This module provides functions for handling robot parameters, including validation, conversion, and default parameter sets for various robot types.
+
+## API Reference
+
+::: jsrm.parameters
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/pcs.md

@@ -0,0 +1,24 @@
+# PCS Systems (General)
+
+The general Piecewise Constant Strain (PCS) implementation provides the core modeling framework for continuum soft robots, based on the discrete Cosserat approach proposed by Renda et al. (2018).
+
+## Overview
+
+This module contains the fundamental PCS implementation that serves as the foundation for more specialized PCS variants. It provides the core mathematical framework for modeling continuum robots using piecewise constant strain assumptions, following the discrete Cosserat approach for multisection soft manipulator dynamics.
+
+## API Reference
+
+::: jsrm.systems.pcs
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source
+
+## References
+
+The PCS (Piecewise Constant Strain) model was originally proposed in:
+
+Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533.

docs/api/pendulum.md

@@ -0,0 +1,18 @@
+# Pendulum Systems
+
+The pendulum module provides implementations for N-link pendulum systems, which are useful for benchmarking and comparison with soft robot systems.
+
+## Overview
+
+The pendulum system implements classical rigid-body dynamics for articulated robots with revolute joints. This serves as a baseline for comparing with continuum soft robot models.
+
+## API Reference
+
+::: jsrm.systems.pendulum
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/planar-hsa.md

@@ -0,0 +1,18 @@
+# Planar HSA Systems
+
+The Planar Handed Shearing Auxetics (HSA) systems provide implementations for soft robots with auxetic properties in planar settings.
+
+## Overview
+
+HSA robots exhibit unique mechanical properties due to their auxetic structure, which allows for interesting deformation patterns and control strategies. This module implements the kinematic and dynamic models for planar HSA robots.
+
+## API Reference
+
+::: jsrm.systems.planar_hsa
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/planar-pcs-sym.md

@@ -0,0 +1,24 @@
+# Planar PCS Symbolic Systems
+
+The symbolic implementation of Planar PCS systems provides pre-computed symbolic expressions for kinematics and dynamics, offering improved computational performance. This implementation is based on the discrete Cosserat approach by Renda et al. (2018).
+
+## Overview
+
+This module contains symbolic derivations of the PCS model equations, based on the discrete Cosserat approach for multisection soft manipulator dynamics (Renda et al., 2018), which are pre-computed using SymPy and then implemented in JAX for fast execution. This approach eliminates the need for numerical differentiation during runtime.
+
+## API Reference
+
+::: jsrm.systems.planar_pcs_sym
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source
+
+## References
+
+The PCS (Piecewise Constant Strain) model was originally proposed in:
+
+Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. *IEEE Transactions on Robotics*, 34(6), 1518-1533.