docs: spell out where the MuJoCo backend differs from Gazebo #77
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: docs | |
| on: | |
| push: | |
| branches: [main, master, gymnasium] | |
| pull_request: | |
| branches: [main, master, gymnasium] | |
| workflow_dispatch: {} | |
| jobs: | |
| sphinx-build: | |
| runs-on: ubuntu-22.04 | |
| steps: | |
| # Check out UniROS WITHOUT submodules; we'll clone the framework | |
| # repos individually below at branch refs matching the current run. | |
| # The submodule gitlinks in UniROS point at older multiros/realros | |
| # SHAs; using them here would render stale docstrings. | |
| - name: Check out UniROS | |
| uses: actions/checkout@v4 | |
| with: | |
| path: UniROS | |
| # The framework + application packages live in separate repos. | |
| # Clone each at the SAME branch ref this workflow is running on | |
| # (gymnasium → gymnasium, feature branches → matching branch, | |
| # etc.) so the docs render the matching versions of every package. | |
| # | |
| # LOCKSTEP REQUIREMENT: these checkouts have no fallback — the | |
| # matching branch MUST exist in multiros / realros / sb3_ros_support | |
| # or actions/checkout fails the job. When opening a feature branch | |
| # in UniROS that touches docs, push the same branch name to the | |
| # other three repos first (an empty no-op commit is enough). | |
| # rl_environments / rl_training_validation are handled below with | |
| # an explicit gymnasium → main fallback because they don't use | |
| # the gymnasium branch convention. | |
| - name: Check out multiros | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: ncbdrck/multiros | |
| ref: ${{ github.head_ref || github.ref_name }} | |
| path: multiros | |
| - name: Check out realros | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: ncbdrck/realros | |
| ref: ${{ github.head_ref || github.ref_name }} | |
| path: realros | |
| - name: Check out sb3_ros_support | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: ncbdrck/sb3_ros_support | |
| ref: ${{ github.head_ref || github.ref_name }} | |
| path: sb3_ros_support | |
| # rl_environments and rl_training_validation use `main` as their | |
| # default branch, NOT `gymnasium` (that's a framework-side convention). | |
| # So when UniROS is on gymnasium, fall back to `main` for these two. | |
| # Other branches (feature / integration branches) still try to match. | |
| - name: Check out rl_environments | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: ncbdrck/rl_environments | |
| ref: ${{ (github.head_ref || github.ref_name) == 'gymnasium' && 'main' || (github.head_ref || github.ref_name) }} | |
| path: rl_environments | |
| - name: Check out rl_training_validation | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: ncbdrck/rl_training_validation | |
| ref: ${{ (github.head_ref || github.ref_name) == 'gymnasium' && 'main' || (github.head_ref || github.ref_name) }} | |
| path: rl_training_validation | |
| # Python 3.8 matches the project's actual runtime (ROS Noetic | |
| # ships only on Ubuntu 20.04 / Python 3.8). Running docs CI on a | |
| # newer interpreter pulled in Sphinx 8.x + docutils 0.21, which | |
| # is stricter about edge-case rST in legacy docstrings that | |
| # users on 3.8 / Sphinx 7.x never see — pure false positives. | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.8" | |
| - name: Install docs build deps | |
| working-directory: UniROS | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/requirements.txt | |
| - name: Syntax-check Python code blocks in docs | |
| working-directory: UniROS | |
| run: python scripts/check_python_code_blocks.py docs -v | |
| - name: Build HTML docs (warnings-as-errors) | |
| working-directory: UniROS | |
| run: sphinx-build -W --keep-going -b html docs docs/_build/html | |
| - name: Upload built docs as artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: html-docs | |
| path: UniROS/docs/_build/html | |
| retention-days: 14 |