Skip to content

Commit 06082e6

Browse files
mstoelzlemstoelzle
authored
Add first version of docs (#10)
* Initial commit for adding documentation * Divide systems into subpages * Fix URL to `tud-phi` organization * Fix some formatting / documentation issues * Update visuals of docs * Update the styling * Update copyright line * Add authors and maintainers page * Add Daniel and Cosimo as authors and cite the PCS paper in all docs * Update `docs.yml` GitHub action * Add status badges to README
1 parent 1bf71b5 commit 06082e6

38 files changed

+2828
-13
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.11'
34+
35+
- name: Install dependencies
36+
run: |
37+
python -m pip install --upgrade pip
38+
pip install -e ".[docs,examples]"
39+
40+
- name: Build documentation
41+
run: |
42+
mkdocs build --clean
43+
44+
- name: Setup Pages
45+
if: github.ref == 'refs/heads/main'
46+
uses: actions/configure-pages@v4
47+
48+
- name: Upload artifact
49+
if: github.ref == 'refs/heads/main'
50+
uses: actions/upload-pages-artifact@v3
51+
with:
52+
path: ./site
53+
54+
deploy:
55+
if: github.ref == 'refs/heads/main'
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
runs-on: ubuntu-latest
60+
needs: build
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,4 +136,7 @@ dmypy.json
136136
# DS_STORE
137137
.DS_Store
138138
*.mp4
139-
*.gif
139+
*.gif
140+
141+
# Documentation build
142+
site/

‎.vscode/settings.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"python-envs.defaultEnvManager": "ms-python.python:conda",
3+
"python-envs.defaultPackageManager": "ms-python.python:conda",
4+
"python-envs.pythonProjects": []
5+
}

‎Makefile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,23 @@ pytestcache-remove:
5454
build-remove:
5555
rm -rf build/
5656

57+
#* Documentation
58+
.PHONY: docs-serve
59+
docs-serve:
60+
conda run --live-stream --name jsrm mkdocs serve
61+
62+
.PHONY: docs-build
63+
docs-build:
64+
conda run --live-stream --name jsrm mkdocs build --clean
65+
66+
.PHONY: docs-build-strict
67+
docs-build-strict:
68+
conda run --live-stream --name jsrm mkdocs build --clean --strict
69+
70+
.PHONY: docs-deploy
71+
docs-deploy:
72+
conda run --live-stream --name jsrm mkdocs gh-deploy --force
73+
5774
.PHONY: cleanup
5875
cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove
5976

‎README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# JAX Soft Robot Modelling
22

3+
[![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)
4+
[![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)
5+
[![PyPI version](https://badge.fury.io/py/jsrm.svg)](https://badge.fury.io/py/jsrm)
6+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7+
[![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)
8+
[![Docs](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://tud-phi.github.io/jax-soft-robot-modelling)
9+
310
This repository contains symbolic derivations of the kinematics and dynamics of various soft robots using Sympy.
411
The symbolic expressions are then implemented in JAX and can be used for fast, parallelizable, and differentiable simulations.
512
So far, we have focused on planar settings and implemented the following soft robots:
@@ -68,6 +75,61 @@ Finally, we can simulate the pendulum
6875
python examples/simulate_pendulum.py
6976
```
7077

78+
## Documentation
79+
80+
The full documentation is available at: https://tud-phi.github.io/jax-soft-robot-modelling
81+
82+
### Building Documentation Locally
83+
84+
To build and serve the documentation locally:
85+
86+
```bash
87+
# Install documentation dependencies
88+
pip install -e ".[docs]"
89+
90+
# Serve documentation with live reload (if mkdocs is in PATH)
91+
mkdocs serve
92+
93+
# OR using conda environment
94+
conda run --live-stream --name jsrm mkdocs serve
95+
```
96+
97+
The documentation will be available at `http://127.0.0.1:8000`.
98+
99+
### Building Documentation for Production
100+
101+
```bash
102+
# Build static documentation (if mkdocs is in PATH)
103+
mkdocs build
104+
105+
# OR using conda environment
106+
conda run --live-stream --name jsrm mkdocs build
107+
108+
# Build with strict mode (for CI/development)
109+
mkdocs build --strict
110+
# OR: conda run --live-stream --name jsrm mkdocs build --strict
111+
112+
# Deploy to GitHub Pages (maintainers only)
113+
mkdocs gh-deploy
114+
# OR: conda run --live-stream --name jsrm mkdocs gh-deploy
115+
```
116+
117+
You can also use the Makefile targets:
118+
119+
```bash
120+
# Serve locally
121+
make docs-serve
122+
123+
# Build documentation
124+
make docs-build
125+
126+
# Build with strict mode checking
127+
make docs-build-strict
128+
129+
# Deploy to GitHub Pages
130+
make docs-deploy
131+
```
132+
71133
## See also
72134

73135
You might also be interested in the following repositories:

‎docs/404.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
7+
# 🤖 404 - Page Not Found
8+
9+
<div class="doc-summary">
10+
<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!
11+
</div>
12+
13+
---
14+
15+
## 🧭 Navigation Help
16+
17+
<div class="feature-grid">
18+
<div class="feature-card">
19+
<h3><span class="icon">🏠</span> [Home](index.md)</h3>
20+
<p>Go back to the main page and start fresh</p>
21+
</div>
22+
23+
<div class="feature-card">
24+
<h3><span class="icon">🚀</span> [Quick Start](user-guide/quick-start.md)</h3>
25+
<p>Jump into hands-on tutorials and examples</p>
26+
</div>
27+
28+
<div class="feature-card">
29+
<h3><span class="icon">📚</span> [API Reference](api/systems.md)</h3>
30+
<p>Browse the complete API documentation</p>
31+
</div>
32+
33+
<div class="feature-card">
34+
<h3><span class="icon">📖</span> [Examples](user-guide/examples.md)</h3>
35+
<p>Explore comprehensive examples and use cases</p>
36+
</div>
37+
</div>
38+
39+
---
40+
41+
## 🔍 Popular Resources
42+
43+
!!! tip "Most Visited Pages"
44+
45+
- **[Installation Guide](installation.md)** - Get JSRM up and running
46+
- **[Planar PCS Systems](api/planar-pcs.md)** - Continuum soft robot documentation
47+
- **[Contributing Guidelines](development/contributing.md)** - Join our community
48+
- **[System Factory Pattern](user-guide/quick-start.md#core-concepts)** - Learn the basics
49+
50+
---
51+
52+
## 🆘 Still Lost?
53+
54+
!!! question "Need help finding something specific?"
55+
56+
=== "🔍 Search"
57+
Use the search box at the top of the page to find what you're looking for.
58+
59+
=== "📧 Contact"
60+
Reach out to us at [[email protected]](mailto:[email protected])
61+
62+
=== "🐛 Report Issue"
63+
If you think this is a broken link, please [report it on GitHub](https://github.com/tud-phi/jax-soft-robot-modelling/issues/new)
64+
65+
---
66+
67+
<div style="text-align: center; margin: 2rem 0;">
68+
<p style="font-size: 1.2rem; color: var(--md-primary-fg-color);">
69+
🤖 <strong>Happy Coding with JSRM!</strong>
70+
</p>
71+
</div>

‎docs/api/integration.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Integration Utilities
2+
3+
Numerical integration methods and utilities for solving differential equations.
4+
5+
## Overview
6+
7+
This module provides various integration schemes including Gauss-Legendre quadrature and other numerical methods used in the robot dynamics computations.
8+
9+
## API Reference
10+
11+
::: jsrm.integration
12+
options:
13+
show_root_heading: true
14+
show_source: false
15+
heading_level: 3
16+
group_by_category: true
17+
docstring_section_style: table
18+
members_order: source

‎docs/api/math-utils.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Math Utilities
2+
3+
Mathematical utility functions used throughout JSRM for various computations.
4+
5+
## Overview
6+
7+
This module provides core mathematical operations including linear algebra utilities, matrix operations, and specialized functions for robotics computations.
8+
9+
## API Reference
10+
11+
::: jsrm.math_utils
12+
options:
13+
show_root_heading: true
14+
show_source: false
15+
heading_level: 3
16+
group_by_category: true
17+
docstring_section_style: table
18+
members_order: source

‎docs/api/parameters.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Parameters
2+
3+
Parameter handling and configuration utilities for robot systems.
4+
5+
## Overview
6+
7+
This module provides functions for handling robot parameters, including validation, conversion, and default parameter sets for various robot types.
8+
9+
## API Reference
10+
11+
::: jsrm.parameters
12+
options:
13+
show_root_heading: true
14+
show_source: false
15+
heading_level: 3
16+
group_by_category: true
17+
docstring_section_style: table
18+
members_order: source

‎docs/api/pcs.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# PCS Systems (General)
2+
3+
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).
4+
5+
## Overview
6+
7+
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.
8+
9+
## API Reference
10+
11+
::: jsrm.systems.pcs
12+
options:
13+
show_root_heading: true
14+
show_source: false
15+
heading_level: 3
16+
group_by_category: true
17+
docstring_section_style: table
18+
members_order: source
19+
20+
## References
21+
22+
The PCS (Piecewise Constant Strain) model was originally proposed in:
23+
24+
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.

0 commit comments

Comments
 (0)