Skip to content

Commit ae60c69

Browse files
ncbdrckncbdrck
committed
Merge cleanup-2026 into gymnasium
2 parents 3c5ff78 + fb1697f commit ae60c69

40 files changed

Lines changed: 5643 additions & 150 deletions

‎.github/workflows/docs.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches: [main, master, gymnasium, cleanup-2026]
6+
pull_request:
7+
branches: [main, master, gymnasium, cleanup-2026]
8+
workflow_dispatch: {}
9+
10+
jobs:
11+
sphinx-build:
12+
runs-on: ubuntu-22.04
13+
14+
steps:
15+
# Check out UniROS WITHOUT submodules; we'll clone the framework
16+
# repos individually below at branch refs matching the current run.
17+
# The submodule gitlinks in UniROS point at older multiros/realros
18+
# SHAs; using them here would render stale docstrings.
19+
- name: Check out UniROS
20+
uses: actions/checkout@v4
21+
with:
22+
path: UniROS
23+
24+
# The framework + application packages live in separate repos.
25+
# Clone each at the SAME branch ref this workflow is running on
26+
# (cleanup-2026 → cleanup-2026, gymnasium → gymnasium, etc.) so
27+
# the docs render the matching versions of every package.
28+
- name: Check out multiros
29+
uses: actions/checkout@v4
30+
with:
31+
repository: ncbdrck/multiros
32+
ref: ${{ github.head_ref || github.ref_name }}
33+
path: multiros
34+
35+
- name: Check out realros
36+
uses: actions/checkout@v4
37+
with:
38+
repository: ncbdrck/realros
39+
ref: ${{ github.head_ref || github.ref_name }}
40+
path: realros
41+
42+
- name: Check out sb3_ros_support
43+
uses: actions/checkout@v4
44+
with:
45+
repository: ncbdrck/sb3_ros_support
46+
ref: ${{ github.head_ref || github.ref_name }}
47+
path: sb3_ros_support
48+
49+
- name: Check out rl_environments
50+
uses: actions/checkout@v4
51+
with:
52+
repository: ncbdrck/rl_environments
53+
ref: ${{ github.head_ref || github.ref_name }}
54+
path: rl_environments
55+
56+
- name: Check out rl_training_validation
57+
uses: actions/checkout@v4
58+
with:
59+
repository: ncbdrck/rl_training_validation
60+
ref: ${{ github.head_ref || github.ref_name }}
61+
path: rl_training_validation
62+
63+
- uses: actions/setup-python@v5
64+
with:
65+
python-version: "3.10"
66+
67+
- name: Install docs build deps
68+
working-directory: UniROS
69+
run: |
70+
python -m pip install --upgrade pip
71+
pip install -r docs/requirements.txt
72+
73+
- name: Build HTML docs (warnings-as-errors)
74+
working-directory: UniROS
75+
run: sphinx-build -W --keep-going -b html docs docs/_build/html
76+
77+
- name: Upload built docs as artifact
78+
uses: actions/upload-artifact@v4
79+
with:
80+
name: html-docs
81+
path: UniROS/docs/_build/html
82+
retention-days: 14

‎.github/workflows/tests.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: tests
2+
3+
on:
4+
push:
5+
branches: [main, master, gymnasium, cleanup-2026]
6+
pull_request:
7+
branches: [main, master, gymnasium, cleanup-2026]
8+
workflow_dispatch: {}
9+
10+
jobs:
11+
pytest:
12+
runs-on: ubuntu-22.04
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
# 3.8 = ROS Noetic's bundled Python (the supported runtime).
17+
# 3.10 = forward-compat check.
18+
# 3.12 is blocked on migrating setup.py from distutils to
19+
# setuptools (distutils was removed from 3.12 stdlib). Re-enable
20+
# once that migration lands.
21+
python-version: ["3.8", "3.10"]
22+
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- uses: actions/setup-python@v5
27+
with:
28+
python-version: ${{ matrix.python-version }}
29+
30+
- name: Install package + test deps
31+
working-directory: uniros
32+
run: |
33+
python -m pip install --upgrade pip
34+
# The package's setup.py imports catkin_pkg + uses distutils (from
35+
# stdlib up to 3.11). Install build deps in the OUTER env, then
36+
# pip install -e with --no-build-isolation so the build subprocess
37+
# can see them. Without --no-build-isolation, pip creates a clean
38+
# build sandbox and catkin_pkg won't be visible there.
39+
pip install setuptools wheel catkin_pkg pytest
40+
# Pin gymnasium to match the supported runtime. gymnasium 1.x
41+
# removed wrapper attribute passthrough that the proxy depends on.
42+
pip install "gymnasium==0.29.1" "gymnasium_robotics==1.2.4" numpy
43+
# Tests stub the rospy ecosystem in conftest.py; no ROS install needed.
44+
pip install -e . --no-build-isolation
45+
46+
- name: Run pytest
47+
working-directory: uniros
48+
run: pytest tests/ -v

‎.readthedocs.yaml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Read the Docs configuration for the UniROS ecosystem docs site.
2+
#
3+
# autodoc reads docstrings from the four framework packages plus
4+
# rl_environments and rl_training_validation. ROS / Gazebo / KDL /
5+
# MoveIt / torch / SB3 imports inside those packages are mocked in
6+
# docs/conf.py so no ROS install is needed on the RTD builder.
7+
#
8+
# https://docs.readthedocs.com/platform/stable/config-file/v2.html
9+
10+
version: 2
11+
12+
build:
13+
os: ubuntu-22.04
14+
tools:
15+
python: "3.10"
16+
17+
# When RTD checks out this repo, the multiros and realros submodules
18+
# are pulled automatically (see ``submodules:`` below). The other
19+
# packages live in separate repos, so we clone them alongside this
20+
# repo's checkout so docs/conf.py can resolve them.
21+
jobs:
22+
post_checkout:
23+
- git clone --depth 1 -b gymnasium https://github.com/ncbdrck/sb3_ros_support.git ../sb3_ros_support
24+
- git clone --depth 1 https://github.com/ncbdrck/rl_environments.git ../rl_environments
25+
- git clone --depth 1 https://github.com/ncbdrck/rl_training_validation.git ../rl_training_validation
26+
27+
# Pull the multiros and realros submodules. UniROS bundles them so a
28+
# single recursive clone gives you the whole framework.
29+
submodules:
30+
include: all
31+
recursive: true
32+
33+
sphinx:
34+
configuration: docs/conf.py
35+
fail_on_warning: false
36+
37+
python:
38+
install:
39+
- requirements: docs/requirements.txt

‎README.md‎

Lines changed: 52 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -111,48 +111,81 @@ git pull # to update the repository
111111
env = gym.make('MyEnv-v0')
112112
```
113113

114-
## Scripheck_repos.sh`
115-
Below is the `check_repos.sh` script. Save this in your `home` directory and run it to check if `multiros` and `realros` are already downloaded.
114+
## Script: `check_repos.sh`
115+
Below is the `check_repos.sh` script. Save it in your `home` directory and run it to check if `multiros` and `realros` are already downloaded.
116116

117117
```bash
118118
#!/bin/bash
119119

120120
# Function to check if a directory is a Git repository
121121
is_git_repo() {
122-
if git -C $1 rev-parse 2>/dev/null; then
122+
if git -C "$1" rev-parse 2>/dev/null; then
123123
return 0
124124
else
125125
return 1
126126
fi
127127
}
128128

129-
# Directories where multiros and realros might exist
130-
MULTIROS_DIR="path/to/multiros" # ~/catkin_ws/src/multiros
131-
REALROS_DIR="path/to/realros" # ~/catkin_ws/src/realros
132-
t: `c
129+
# Directories where multiros and realros might exist.
130+
# Adjust these to match your workspace.
131+
MULTIROS_DIR="$HOME/catkin_ws/src/multiros"
132+
REALROS_DIR="$HOME/catkin_ws/src/realros"
133+
133134
# Check multiros
134-
if [ -d "$MULTIROS_DIR" ] && is_git_repo $MULTIROS_DIR; then
135-
echo "multiros repository found."
135+
if [ -d "$MULTIROS_DIR" ] && is_git_repo "$MULTIROS_DIR"; then
136+
echo "multiros repository found at $MULTIROS_DIR"
136137
else
137-
echo "multiros repository not found."
138+
echo "multiros repository not found (looked in $MULTIROS_DIR)"
138139
fi
139140

140141
# Check realros
141-
if [ -d "$rREALROS_DIR" ] && is_git_repo $REALROS_DIR; then
142-
echo "realros repository found."
142+
if [ -d "$REALROS_DIR" ] && is_git_repo "$REALROS_DIR"; then
143+
echo "realros repository found at $REALROS_DIR"
143144
else
144-
echo "realros repository not found."
145+
echo "realros repository not found (looked in $REALROS_DIR)"
145146
fi
146147
```
147148

148-
Replace `path/to/multiros` and `path/to/realros` with the actual paths where you expect these repositories to be.
149-
Since we are working with ROS, the path typically should be in the format of `~/ros_workspace_ws/src/`.
149+
Update `MULTIROS_DIR` and `REALROS_DIR` to match where these repositories live in your workspace. The typical layout for a ROS catkin workspace is `~/<workspace_name>_ws/src/<repo_name>/`.
150+
151+
## Documentation
152+
153+
Full documentation for the ecosystem — installation, ready-made
154+
environments, environment creation (sim and real), training with
155+
any gymnasium-compatible framework, joint sim+real training, and
156+
the API reference — lives in the [`docs/`](docs/) directory of
157+
this repository and is built with Sphinx.
158+
159+
To preview locally:
160+
161+
```bash
162+
cd ~/catkin_ws/src/UniROS
163+
pip install -r docs/requirements.txt
164+
sphinx-build -b html docs docs/_build/html
165+
xdg-open docs/_build/html/index.html
166+
```
150167

151168
## Cite
152169

153-
If you use UniROS in your research or work and would like to cite it, you can use the following citation:
170+
If you use UniROS in your research or work and would like to cite it, please cite the journal paper:
171+
172+
```bibtex
173+
@Article{s25185679,
174+
AUTHOR = {Kapukotuwa, Jayasekara and Lee, Brian and Devine, Declan and Qiao, Yuansong},
175+
TITLE = {UniROS: A Unified Framework for ROS-Based Reinforcement Learning Across Simulated and Real-World Robotics},
176+
JOURNAL = {Sensors},
177+
VOLUME = {25},
178+
YEAR = {2025},
179+
NUMBER = {18},
180+
PAGES = {5679},
181+
URL = {https://www.mdpi.com/1424-8220/25/18/5679},
182+
ISSN = {1424-8220},
183+
DOI = {10.3390/s25185679},
184+
}
185+
```
186+
187+
The earlier conference paper on the MultiROS sub-package:
154188

155-
Articles:
156189
```bibtex
157190
@article{kapukotuwa_uniros_2025,
158191
title = {UniROS: A Unified Framework for ROS-Based Reinforcement Learning Across Simulated and Real-World Robotics},
@@ -180,7 +213,9 @@ Articles:
180213
pages = {1098--1103},
181214
}
182215
```
216+
183217
Repository:
218+
184219
```bibtex
185220
@misc{uniros,
186221
author = {Kapukotuwa, Jayasekara},

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎docs/_static/.gitkeep‎

Whitespace-only changes.

0 commit comments

Comments
 (0)