From 59cf51b8bb1b24ebfcb7f536e21340e6f6268850 Mon Sep 17 00:00:00 2001 From: yunlishao-vibe <267182001+yunlishao-vibe@users.noreply.github.com> Date: Wed, 23 Sep 2026 17:18:02 -0400 Subject: [PATCH 1/4] docs(#137): clean RTD build, docs PR check, rebuild docs per release channel Fix the 31 Sphinx warnings (landing-page include, dead links, headings) and fail RTD builds on warnings. Links out of doc/ become GitHub links at the built commit. docs.yml builds the site on every PR; release.yml's new docs-publish job rebuilds the channel's RTD version after publishing. --- .github/workflows/docs.yml | 37 +++++++++++++++++ .github/workflows/release.yml | 36 +++++++++++++++++ .readthedocs.yml | 2 +- README.md | 2 + doc/CARLAdoc.md | 2 +- doc/CarMakerDoc.md | 6 +-- doc/Carla_Linux_building.md | 2 +- doc/Carla_Windows_building.md | 4 +- doc/DEVELOPER_GUIDE.md | 47 +++++++++++++++++++++- doc/VISSIMdoc.md | 2 +- doc/_ext/repo_links.py | 75 +++++++++++++++++++++++++++++++++++ doc/conf.py | 12 ++++-- doc/gui-design/wireframes.md | 2 - doc/index.rst | 6 ++- 14 files changed, 216 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 doc/_ext/repo_links.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..31d974e5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,37 @@ +name: Docs + +# Builds the Read the Docs site on every PR that can change it, with warnings as +# errors, so a broken link or a bad toctree entry fails here instead of on RTD +# after merge. Same Python and requirements as .readthedocs.yml. (#137) +# +# Publishing is not done here: RTD builds each channel (stable, vX.Y.Z-alpha, +# vX.Y.Z-beta) when release.yml publishes it - see the docs-publish job there. + +# No paths filter: doc/ links into the rest of the repo (tests/, CarMaker/, +# CLAUDE.md, ...), so moving or deleting a file anywhere can dangle a docs link. +# An allow-list would silently miss the next directory someone links to; the +# build is ~1 min, so it just runs. +on: + pull_request: + branches: [dev, main, 'dev_v*', 'beta_v*'] + +jobs: + sphinx: + runs-on: ubuntu-latest + steps: + # Depth 1 but the whole tree: the link rewriter checks that each target + # exists. ~230 MB; history (the ~1 GB part) is not needed. + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + submodules: false + + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install doc requirements + run: python -m pip install -r doc/requirements_doc.txt + + - name: Build (warnings are errors) + run: python -m sphinx -T -W --keep-going -b html doc _build/html diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6ab65eef..15bff1d6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -506,3 +506,39 @@ jobs: # --clobber replaces only this asset name; the Windows bundle on the # same rolling release is untouched. gh release upload "$CHANNEL_TAG" "$want" --repo "$GITHUB_REPOSITORY" --clobber + + # Read the Docs serves one docs version per channel under the channel's own + # name (stable, vX.Y.Z-beta, vX.Y.Z-alpha), built from the tag published above + # (#137). Ask RTD to rebuild it here, so the docs move exactly when the channel + # does, whatever RTD's webhook makes of a tag that was deleted and recreated. + docs-publish: + name: Rebuild the channel's docs on Read the Docs + needs: build-publish + if: needs.build-publish.outputs.publish == 'true' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish)) + runs-on: ubuntu-latest + steps: + - name: Trigger the RTD build for the channel's version + env: + RTD_TOKEN: ${{ secrets.RTD_TOKEN }} + CHANNEL_TAG: ${{ needs.build-publish.outputs.tag }} + run: | + if [ -z "$RTD_TOKEN" ]; then + echo "::warning::No RTD_TOKEN secret - the $CHANNEL_TAG docs were not rebuilt." + exit 0 + fi + api=https://app.readthedocs.org/api/v3/projects/real-sim + # RTD learns about the recreated tag from the webhook. Until it has + # synced, the version can be missing or still inactive, so sync + retry. + for attempt in 1 2 3 4 5 6; do + code=$(curl -sS -o resp.json -w '%{http_code}' -X POST \ + -H "Authorization: Token $RTD_TOKEN" "$api/versions/$CHANNEL_TAG/builds/") + if [ "$code" = 202 ]; then + echo "RTD build for $CHANNEL_TAG: $(jq -r '.build.urls.build' resp.json)" + exit 0 + fi + echo "attempt $attempt: HTTP $code $(cat resp.json)" + curl -sS -o /dev/null -X POST -H "Authorization: Token $RTD_TOKEN" "$api/sync-versions/" || true + sleep 20 + done + echo "::error::Read the Docs would not build '$CHANNEL_TAG'. Check the version exists and is active (RTD automation rule for channel tags)." + exit 1 diff --git a/.readthedocs.yml b/.readthedocs.yml index e3ae4ee2..7ffc3678 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,7 +7,7 @@ build: sphinx: configuration: doc/conf.py - fail_on_warning: false + fail_on_warning: true python: install: diff --git a/README.md b/README.md index 1d6c222c..86362a1f 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,14 @@ zhoua@ornl.gov ## About + This interface is part of the **Real-Sim** project funded by Department of Energy (DOE)-Vehicle Technology Office (VTO)-Energy Efficient Mobility Systems (EEMS) program. It is part of the core tools of EEMS. Real-Sim develops a multi-resolution X-in-the-loop (XIL) simulation framework to support inclusive testing and evaluation of emerging technologies such as connected and automated vehicles. The Real-Sim framework connects different simulation components and integrates various traffic and vehicle simulation tools, virtual environments, and XIL systems through a Flexible Interface for XIL Simulation (FIXS). Connections among different tools are transparent to users and handled by the interface behind the scenes. Co-simulation of various vehicle and traffic simulation tools with different XIL systems can be easily achieved and become a transparent "plug-and-play" process to users. **Real-Sim Project Lead**: Oak Ridge National Lab\ **Real-Sim Project Team**: University of Georgia, University of Texas-Dallas + **Links to current project presentation**\ https://www1.eere.energy.gov/vehiclesandfuels/downloads/2024_AMR/EEMS101_Chen_2024_o.pdf \ diff --git a/doc/CARLAdoc.md b/doc/CARLAdoc.md index 25c9754f..f0dc0c0d 100644 --- a/doc/CARLAdoc.md +++ b/doc/CARLAdoc.md @@ -129,7 +129,7 @@ CarlaSetup: # whether or not enable Carla (default: false) EnableCosimulation: true - EnableVerboseLog: false + EnableVerboseLog: false # whether or not enable external control # if set to true, the sumo vehicles will be updated according to the carla vehicles' state # if set to false, the carla will be only visualizing the sumo vehicles diff --git a/doc/CarMakerDoc.md b/doc/CarMakerDoc.md index 9ce9e1cf..93796321 100644 --- a/doc/CarMakerDoc.md +++ b/doc/CarMakerDoc.md @@ -46,7 +46,7 @@ Please start with reading through the documentation, and playwith included Examp - VirtrualEnvironment.lib To simplify CarMaker project build process, we will build a library called VirtrualEnvironment.lib that contains all the -required helper functions. Open [VirtualEnvironment.sln](..%2FVirtualEnvironment%2FVirtualEnvironment.sln) +required helper functions. Open [VirtualEnvironment.sln](../VirtualEnvironment/VirtualEnvironment.sln) inside the VirtualEnvironment folder using Visual Studio 2022. in Visual Studio 2022, find the solution explorer window on the right of the screen, right click the _VirtualEnvironment_, select _Properties_, Then in the Property Page, find C/C++ -> General -> Additional Include Directories. Edit the carmaker version if necessary. And make sure yaml-cpp are included: ![VirtualEvn_cppsetup.png](img/VirtualEvn_cppsetup.png) @@ -280,7 +280,7 @@ Using either relative path to the working directory or absolute path are OK ### Setup CM dSPACE #### Obtain dSPACE library -RealSim comes with precompiled dSPACE library file that can be used directly under \CommonLib. If plan to use these libraries directly, can skip the next section and go to [this section](#prepare-for-dspace-build-configuration-desk) directly. Otherwise, follow the next section to compile customized dSPACE library. +RealSim comes with precompiled dSPACE library file that can be used directly under \CommonLib. If plan to use these libraries directly, can skip the next section and go to [this section](#prepare-for-dspace-build-configurationdesk) directly. Otherwise, follow the next section to compile customized dSPACE library. #### Compile dSPACE library @@ -304,7 +304,7 @@ Tips: You can copy the `DsBuildLibrary.mk` into the CommonLib Folder and rename _Refer to the following dSPACE documentation https://www.dspace.com/en/inc/home/support/kb/faqs/faq012.cfm._ After successfully execute the `buildRS_XXXX.bat` file, you should have something appear on command line window like -```commandline +```text ... C:\Program Files\Common Files\dSPACE\CFD Compiler 24.1\target\x86_64-linux-gnu\bin\x86_64-linux-gnu-ar.exe: creating libRealSimDsLib_2024a_CM13_1_3.a a - SocketHelper.o64 diff --git a/doc/Carla_Linux_building.md b/doc/Carla_Linux_building.md index ce231870..32172963 100644 --- a/doc/Carla_Linux_building.md +++ b/doc/Carla_Linux_building.md @@ -249,7 +249,7 @@ This compiles the Carla UE4 plugin and the `CarlaUE4Editor` target (long the fir --- -#### Issue 7 — `Permission denied` creating content directories +### Issue 7 — `Permission denied` creating content directories The build fails late with: diff --git a/doc/Carla_Windows_building.md b/doc/Carla_Windows_building.md index 05c9993b..825be4e7 100644 --- a/doc/Carla_Windows_building.md +++ b/doc/Carla_Windows_building.md @@ -1,4 +1,4 @@ -## CARLA 0.9.15 Windows Build Guide +# CARLA 0.9.15 Windows Build Guide This document provides a practical guide for building CARLA 0.9.15 on Windows. @@ -235,5 +235,3 @@ Ensure the following packages are installed specifically for Python 3.10, not ju ``` py -3.10 -m pip install setuptools wheel "numpy<2.0.0" ``` - ---- \ No newline at end of file diff --git a/doc/DEVELOPER_GUIDE.md b/doc/DEVELOPER_GUIDE.md index 20f2d14d..6534a3b9 100644 --- a/doc/DEVELOPER_GUIDE.md +++ b/doc/DEVELOPER_GUIDE.md @@ -7,6 +7,7 @@ This guide provides comprehensive information about the FIXS repository structur - [Build Scripts](#build-scripts) - [Setup Scripts](#setup-scripts) - [Usage Guide](#usage-guide) +- [Documentation (Read the Docs)](#documentation-read-the-docs) --- @@ -98,6 +99,48 @@ GitHub-specific configuration (workflows, issue templates, CI/CD). --- +## Documentation (Read the Docs) + +The docs site is https://real-sim.readthedocs.io. It carries one version per +release channel, under the channel's name: + +| Branch | Docs version | +|---|---| +| `main` | `stable` (the default) | +| `beta_vX.Y.Z` | `vX.Y.Z-beta` | +| `dev_vX.Y.Z` | `vX.Y.Z-alpha` | + +Each version is built from its channel's tag, so the docs move when the channel is +published. The `docs-publish` job at the end of `.github/workflows/release.yml` +asks Read the Docs to rebuild that version right after the release is published, +using the `RTD_TOKEN` repository secret. On the Read the Docs side, an automation +rule activates the channel tags as they appear. + +A build clones the repo at that commit, reads `.readthedocs.yml`, installs +`doc/requirements_doc.txt`, and runs Sphinx on `doc/` with `doc/conf.py`. Warnings +are errors. + +Writing docs: +- A page must be listed in a `toctree` in `doc/index.rst`, or it is built but + unreachable. +- Link repo files outside `doc/` relatively (`../tests/Vissim/Ipg/`), so the link + also works on GitHub. On Read the Docs, `doc/_ext/repo_links.py` turns each one + into a GitHub link at the commit being built. A link to a file that does not + exist fails the build. + +Checking a change: every PR runs `.github/workflows/docs.yml`, which builds the site +with warnings as errors. To build locally: + +```bash +pip install -r doc/requirements_doc.txt +python -m sphinx -W --keep-going -b html doc _build/html +``` + +With Windows Python 3.10 the build can crash intermittently inside docutils; build +under WSL or Python 3.11 instead. + +--- + ## Known Limitations and Technical Debt This section documents known rough edges in the codebase for contributors. @@ -448,5 +491,5 @@ For simulator-specific details, see: - [CARLA Interface](CARLAdoc.md) For general setup and configuration: -- [Configuration Guide](../ConfigSetup.md) -- [Setup Guide](../setupGuide.md) +- [Configuration Guide](ConfigSetup.md) +- [Setup Guide](setupGuide.md) diff --git a/doc/VISSIMdoc.md b/doc/VISSIMdoc.md index 5e77e862..065a819e 100644 --- a/doc/VISSIMdoc.md +++ b/doc/VISSIMdoc.md @@ -278,7 +278,7 @@ VISSIM does not have a true speed limit concept, rather, desired speed decisions The getVissimNetworkInfo.py will attempt to interpret the speed limit from name of desired speed distributions, but users **MUST** check the DesSpdDistr2SpeedLimitMap.csv manually to make sure it is correct. -In addition, VISSIM does not have a complete route concept for each vehicle, rather, each vehicle will be assigned a decision at each static route decision point. Hence, it is infeasible to obtain all following routes and links a vehicle will be driven until it travels to each static route decision point. To counter this, users **MUST** supply a Routes.yaml file to specify routes of vehicles of interest. This Routes.yaml **MUST** be in the same folder as VISSIM .inpx files. Examples of route definitions (download [here](Routes.yaml)): +In addition, VISSIM does not have a complete route concept for each vehicle, rather, each vehicle will be assigned a decision at each static route decision point. Hence, it is infeasible to obtain all following routes and links a vehicle will be driven until it travels to each static route decision point. To counter this, users **MUST** supply a Routes.yaml file to specify routes of vehicles of interest. This Routes.yaml **MUST** be in the same folder as VISSIM .inpx files. Examples of route definitions (download [here](../tests/Vissim/networks/speedLimit/Routes.yaml)): ```yaml Routes: # example route 1 diff --git a/doc/_ext/repo_links.py b/doc/_ext/repo_links.py new file mode 100644 index 00000000..f9e6ea83 --- /dev/null +++ b/doc/_ext/repo_links.py @@ -0,0 +1,75 @@ +"""Point Markdown links that leave doc/ at the file on GitHub. + +The pages are also read on GitHub, so they link repo files relatively +(``../tests/Vissim/Ipg/``, ``../CLAUDE.md``). Sphinx only builds doc/, so on +Read the Docs those links have no target. This rewrites each one whose target +exists in the repo to a GitHub URL pinned to the commit being built, so every +docs version links the code it was built from. A link whose target does not +exist anywhere is left alone, so MyST still warns about it. +""" +import functools +import os +import subprocess +from urllib.parse import unquote + +from docutils import nodes +from sphinx import addnodes +from sphinx.transforms.post_transforms import SphinxPostTransform + + +@functools.lru_cache(maxsize=None) +def _commit(repo_root): + sha = os.environ.get("READTHEDOCS_GIT_COMMIT_HASH") + if sha: + return sha + try: + return subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=repo_root, text=True, + stderr=subprocess.DEVNULL, + ).strip() + except (OSError, subprocess.CalledProcessError): + return "main" # local build outside a usable checkout + + +class RepoLinks(SphinxPostTransform): + default_priority = 8 # MyST's resolver runs at 9 and warns on what's left + + def run(self, **kwargs): + srcdir = os.path.abspath(self.env.srcdir) + repo_root = os.path.dirname(srcdir) + base_url = "{}/{{kind}}/{}/{{path}}".format( + self.config.repo_links_github.rstrip("/"), _commit(repo_root) + ) + for node in list(self.document.findall(addnodes.pending_xref)): + if node.get("reftype") != "myst": + continue + if node["refdomain"] == "doc": + # MyST already made these relative to doc/ and dropped ".md". + target, anchor = node["reftarget"] + ".md", node.get("reftargetid") + path = os.path.join(srcdir, target) + else: + target, _, anchor = unquote(node["reftarget"]).partition("#") + refdoc = self.env.doc2path(node.get("refdoc", self.env.docname)) + path = os.path.join(os.path.dirname(refdoc), target) + path = os.path.normpath(path) + rel = os.path.relpath(path, repo_root) + outside_doc = os.path.relpath(path, srcdir).startswith("..") + if rel.startswith("..") or not outside_doc or not os.path.exists(path): + continue + url = base_url.format( + kind="tree" if os.path.isdir(path) else "blob", + path=rel.replace(os.sep, "/"), + ) + if anchor: + url += "#" + anchor + ref = nodes.reference("", "", refuri=url, internal=False) + ref.extend(child.deepcopy() for child in node[0].children) + if not ref.children: + ref.append(nodes.literal(target, target)) + node.replace_self(ref) + + +def setup(app): + app.add_config_value("repo_links_github", "", "env") + app.add_post_transform(RepoLinks) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/doc/conf.py b/doc/conf.py index 828224fa..8b2c2331 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,10 +2,13 @@ import os, sys from datetime import datetime sys.path.insert(0, os.path.abspath("..")) +sys.path.insert(0, os.path.abspath("_ext")) # Project information project = "Real-Sim" -author = "Real-Sim Team " -release = "0.10" # version string +author = "Real-Sim Team " +# The version RTD is building (v0.9.1-alpha, stable, latest). RTD clones +# shallow and without tags, so git describe can't answer this there. +release = os.environ.get("READTHEDOCS_VERSION_NAME", "local") root_doc = "index" # ensure doc/index.md or doc/index.rst exists #General configuration @@ -13,9 +16,12 @@ "myst_parser", # enable Markdown (MyST) "sphinx.ext.autodoc", # pull in docstrings "sphinx.ext.napoleon", # Google/NumPy style docstrings - "sphinx.ext.viewcode" + "sphinx.ext.viewcode", + "repo_links", # links out of doc/ -> GitHub at the built commit ] +repo_links_github = "https://github.com/ORNL-Real-Sim/FIXS" + templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] diff --git a/doc/gui-design/wireframes.md b/doc/gui-design/wireframes.md index 70aafe5f..60938d5a 100644 --- a/doc/gui-design/wireframes.md +++ b/doc/gui-design/wireframes.md @@ -116,5 +116,3 @@ While in simulation setup, after clicking advanced Vehicle Fields, this box will **Purpose:** Generates a ready-to-use `config.yaml` file based on user inputs, eliminating the need for manual configuration. - ---- \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 7325a62c..98f24ff3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,8 +2,10 @@ Real-Sim Documentation ====================== -.. mdinclude:: README.md - :start-line: 1 +.. include:: ../README.md + :parser: myst_parser.sphinx_ + :start-after: + :end-before: .. toctree:: :maxdepth: 2 From 84fe837e0ad81e46a2ddb0bef714434d67b462b2 Mon Sep 17 00:00:00 2001 From: yunlishao-vibe <267182001+yunlishao-vibe@users.noreply.github.com> Date: Wed, 23 Sep 2026 17:52:30 -0400 Subject: [PATCH 2/4] docs(#137): one getting-started path, Releases and About pages, stale build refs Merge installation/usage/setupGuide into getting-started, turn the changelog stub into a Releases page (channels -> docs versions), include About from the README, and fix stale script names and channel tables in BUILD and the developer guide. --- CLAUDE.md | 15 ++++--- README.md | 8 ++-- doc/BUILD.md | 31 +++++++------ doc/CarMakerDoc.md | 4 +- doc/DEVELOPER_GUIDE.md | 78 +++++++++++---------------------- doc/about.md | 5 ++- doc/changelog.md | 32 +++++++++++--- doc/getting-started.md | 56 +++++++++++++++++------- doc/index.rst | 3 -- doc/installation.md | 37 ---------------- doc/setupGuide.md | 99 ------------------------------------------ doc/usage.md | 32 -------------- 12 files changed, 127 insertions(+), 273 deletions(-) delete mode 100644 doc/installation.md delete mode 100644 doc/setupGuide.md delete mode 100644 doc/usage.md diff --git a/CLAUDE.md b/CLAUDE.md index 20c2d41f..9eeaff71 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -91,14 +91,14 @@ scripts\dispatch\2_core_components.bat # VISSIM driver models only scripts\dispatch\3_vissim_components.bat -# CarMaker (auto-generates BuildConfig files based on dependencies.yaml) -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1 +# CarMaker executables +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5a_carmaker_components.ps1 # dSPACE libraries -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4b_carmaker_dspace.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5b_carmaker_dspace.ps1 # MATLAB MEX file -powershell -ExecutionPolicy Bypass -File scripts\dispatch\5_mex_realsim_socket.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\6_mex_realsim_socket.ps1 ``` ### Build System Features @@ -490,7 +490,7 @@ Forward-looking decisions for unifying the virtual-environment bridges (CarMaker - **`TrafficHelper.cpp` (~1743 lines)** — SUMO and VISSIM logic is fully interleaved; tracked in milestone 0.8.0. Avoid adding to it; route new functionality to helper sub-files instead. - **`mainTrafficLayer.cpp` (~1396 lines)** — The main() function does too much directly. Issue #113 tracks a refactor. Prefer adding logic in helper classes, not directly in main. - **`ConfigHelper.cpp` (~1169 lines)** — Has dead `// TODO: add code` branches and commented-out error blocks; safe to clean up but not urgent. -- **`MsgHelper.py` (~28k lines)** — Almost certainly has dead code paths. Any changes there should be narrow and tested; full audit deferred. +- **`MsgHelper.py` (~680 lines)** — Likely has dead code paths. Any changes there should be narrow and tested; full audit deferred. ### No automated CI - Python unit tests run locally only (`tests/Python/unit/`). Issue #57 tracks GitHub Actions setup. When suggesting test commands, always direct to `python -m pytest tests/Python/unit/ -v` — this is the one simulator-free path. @@ -503,8 +503,9 @@ Forward-looking decisions for unifying the virtual-environment bridges (CarMaker - External contributors see `ProprietaryFiles/` as an inaccessible submodule — don't ask them to modify it. ### Documentation gaps (issue #137) -- RTD `doc/BUILD.md` and `doc/CarlaDoc.md` are orphaned from the TOC — they build but aren't linked in `index.rst`. -- Python CommonLib (`ConfigHelper.py`, `MsgHelper.py`, `SocketHelper.py`) has zero docstrings; Sphinx autodoc will produce empty pages until added. +- The docs build clean with warnings as errors (RTD `fail_on_warning` + the `docs.yml` PR check); how versions are published is in `doc/DEVELOPER_GUIDE.md` → Documentation. +- Still open: the tutorials (`doc/tutorials/`) are stale and should be rebuilt on `tests/Python/SimpleEchoClient`. +- Python CommonLib (`ConfigHelper.py`, `MsgHelper.py`, `SocketHelper.py`) has almost no docstrings, and `doc/api/index.md` is still a stub; autodoc waits on the docstrings. - C++ headers (`ConfigHelper.h`, `SocketHelper.h`, `MsgHelper.h`) have no Doxygen comments; C++ API doc is deferred until issue #137 is addressed. ### Build system diff --git a/README.md b/README.md index 86362a1f..5d9dc218 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # Flexible Interface for XIL Simulation (FIXS) + ## FIXS Contacts -**Primary Maintainer**: University of Georgia\ +**Primary Maintainer**: University of Georgia Oak Ridge National Lab PIs Max Chen\ @@ -30,6 +31,7 @@ https://www1.eere.energy.gov/vehiclesandfuels/downloads/2022_AMR/eems067_deter_2 https://www.energy.gov/sites/default/files/2021-06/eems101_deter_2021_o_5-19_645pm_LR_ML.pdf Publication list is upcoming... + # Other links This README contains general information of the interface. For specific documentation of different simulators, check the following links: @@ -133,8 +135,8 @@ scripts\dispatch\2_core_components.bat # VISSIM components only scripts\dispatch\3_vissim_components.bat -# CarMaker components only (auto-generates BuildConfig files) -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1 +# CarMaker components only +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5a_carmaker_components.ps1 ``` For complete build system documentation including Debug/Release configurations, troubleshooting, and architecture details, see **[doc/BUILD.md](doc/BUILD.md)**. diff --git a/doc/BUILD.md b/doc/BUILD.md index 581b57b7..3701931d 100644 --- a/doc/BUILD.md +++ b/doc/BUILD.md @@ -209,20 +209,20 @@ The release build process executes the following steps: - `DriverModel_RealSim_legacy.dll` - VISSIM driver model, legacy/frozen (long API, VISSIM ≤ 2020) - Output: `ProprietaryFiles/VISSIMserver/` + copied to `build/` -4. **CarMaker Components** (`4a_carmaker_components.ps1`) +4. **CarMaker Components** (`5a_carmaker_components.ps1`) - Generates BuildConfig Python files for each CarMaker version - `CarMaker.win64.exe` - CarMaker Office executables - `libcarmaker4sl.mexw64` - CarMaker for Simulink MEX files - Built for each version in `dependencies.yaml` (e.g., CM11, CM13) - Output: `CarMaker/CM*/` + copied to `build/CarMaker/` -5. **dSPACE Libraries** (`4b_carmaker_dspace.ps1`) - Optional +5. **dSPACE Libraries** (`5b_carmaker_dspace.ps1`) - Optional - `libRealSimDsLib_2024a_CM*.a` - Version-specific dSPACE libraries - Only built if dSPACE ConfigurationDesk is detected - Built for each CarMaker version - Output: `CommonLib/` + copied to `build/CarMaker/` -6. **MEX RealSimSocket** (`5_mex_realsim_socket.ps1`) - Optional +6. **MEX RealSimSocket** (`6_mex_realsim_socket.ps1`) - Optional - `RealSimSocket.mexw64` - MATLAB interface for socket communication - Only built if MATLAB is detected - Output: `CommonLib/` + copied to `build/` @@ -265,14 +265,19 @@ FIXS releases are produced by a GitHub Actions pipeline (`.github/workflows/rele - **Public source → built on the hosted runner every push** (`windows-2022`, matching the VS 2022 generator; `windows-latest` ships VS 2026 and is incompatible): yaml-cpp, `TrafficLayer.exe`, `CoordMerge.exe`, `VirtualEnvironment.lib` (SDK-free on the 0.9.0 train, #174), and all `Carla/` + `CommonLib` Python. No private submodule, no token. - **Licensed-toolchain source → built manually on a licensed workstation**: the VISSIM DriverModel DLLs, CarMaker executables + CM4SL MEX, dSPACE libraries, and the MATLAB MEX. These need installed proprietary toolchains, so the hosted runner cannot build them. They ship as a prebuilt **bundle** that CI overlays into the build. -The hosted path is made proprietary-aware by the `RS_FIXS_AUTOMATION` environment flag, which tells `dispatch.bat` to skip the licensed steps (3 / 4a / 4b / 5) and consume the downloaded bundle instead. +The hosted path is made proprietary-aware by the `RS_FIXS_AUTOMATION` environment flag, which tells `dispatch.bat` to skip the licensed steps (VISSIM 3 / CarMaker 5a / dSPACE 5b / MEX 6) and consume the downloaded bundle instead. ### Rolling release channels | Branch | Rolling prerelease | Notes | |--------|--------------------|-------| -| `main` | `latest` | current train | -| `dev_v0.9.0` | `v0.9.0-alpha` | 0.9.0 train (SDK-free VirtualEnvironment, #174) | +| `main` | `stable` | release tier | +| `beta_vX.Y.Z` | `vX.Y.Z-beta` | test tier | +| `dev_vX.Y.Z` | `vX.Y.Z-alpha` | dev tier (e.g. `dev_v0.9.0` → `v0.9.0-alpha`, SDK-free VirtualEnvironment, #174) | + +`scripts/dispatch/release_channel.ps1` owns this mapping. Each channel also has a +Read the Docs version under the same name (see the Developer Guide's documentation +section). On every push to a release branch the pipeline builds the public core, overlays the matching proprietary bundle, packs one canonical zip, and (re)publishes the rolling prerelease anchored to that commit. Pull requests build + package only (no publish), and upload the zip as a workflow artifact for inspection. @@ -342,7 +347,7 @@ Builds VISSIM driver model DLLs. Run this when modifying VISSIM interface code. #### 4. CarMaker Components Only ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5a_carmaker_components.ps1 ``` Builds CarMaker executables. Automatically: - Reads CarMaker versions from `dependencies.yaml` @@ -352,13 +357,13 @@ Builds CarMaker executables. Automatically: #### 5. dSPACE Libraries Only ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4b_carmaker_dspace.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5b_carmaker_dspace.ps1 ``` Builds dSPACE libraries for CarMaker HIL integration. Run this when modifying dSPACE interface code. #### 6. MEX RealSimSocket Only ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\5_mex_realsim_socket.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\6_mex_realsim_socket.ps1 ``` Builds MATLAB MEX file for socket communication. Run this when modifying MATLAB interface code. @@ -376,7 +381,7 @@ scripts\dispatch\3_vissim_components.bat **Scenario 3: Modified CarMaker User.c or integration** ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5a_carmaker_components.ps1 ``` **Scenario 4: Testing full release package** @@ -506,7 +511,7 @@ The `detect_tool_paths.ps1` script automatically locates installed tools: CarMaker builds require a BuildConfig Python file that specifies compiler settings, include paths, and library dependencies. The build system automatically generates these: **Process:** -1. `4a_carmaker_components.ps1` reads `dependencies.yaml` +1. `5b_carmaker_dspace.ps1` reads `dependencies.yaml` 2. For each CarMaker version (e.g., 11.1.2, 13.1.3): - Detects MATLAB version - Locates CarMaker installation @@ -527,7 +532,7 @@ If you need custom BuildConfig settings, you can: 2. Manually edit the generated Python file 3. Re-run CarMaker build -Note: Re-running `4a_carmaker_components.ps1` will regenerate and overwrite custom changes. +Note: Re-running `5b_carmaker_dspace.ps1` will regenerate and overwrite custom changes. ## Troubleshooting @@ -571,7 +576,7 @@ Error: Could not find MATLAB installation - Ensure MATLAB is installed - Update `dependencies.yaml` with correct MATLAB version - Check MATLAB registry entries exist -- Try specifying MATLAB path manually in `5_mex_realsim_socket.ps1` +- Try specifying MATLAB path manually in `6_mex_realsim_socket.ps1` --- diff --git a/doc/CarMakerDoc.md b/doc/CarMakerDoc.md index 93796321..edf6725f 100644 --- a/doc/CarMakerDoc.md +++ b/doc/CarMakerDoc.md @@ -288,7 +288,7 @@ RealSim comes with precompiled dSPACE library file that can be used directly und The dispatch system automatically builds dSPACE libraries for all CarMaker versions when dSPACE is detected: ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4b_carmaker_dspace.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5b_carmaker_dspace.ps1 ``` This script: @@ -354,7 +354,7 @@ Note: currently, it is only for SCALEXIO and configuration desk dSPACE implement The dispatch system automatically generates CarMaker BuildConfig Python files with correct dSPACE settings: ```batch -powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1 +powershell -ExecutionPolicy Bypass -File scripts\dispatch\5a_carmaker_components.ps1 ``` This generates `RS_CM{major}_{minor}_{patch}_BuildConfig_{matlab}.py` files with: diff --git a/doc/DEVELOPER_GUIDE.md b/doc/DEVELOPER_GUIDE.md index 6534a3b9..827c9305 100644 --- a/doc/DEVELOPER_GUIDE.md +++ b/doc/DEVELOPER_GUIDE.md @@ -25,8 +25,8 @@ Output directory for compiled executables and libraries, including: CarMaker-specific integration scripts and configuration files for dSPACE/CarMaker co-simulation. **Python Scripts:** -- `RS_CM_BuildConfig_r2021b.py` - Build configuration script for CarMaker with Matlab R2021b. Configures dSPACE ConfigurationDesk to compile CarMaker HIL executables with Real-Sim libraries. Handles DDE communication with CarMaker GUI. -- `RS_CM_BuildConfig_r2019b.py` - Build configuration script for CarMaker with Matlab R2019b (older version compatibility) +- `RS_CM_BuildConfig_.py` (e.g. `RS_CM13_1_3_BuildConfig_2024a.py`) - dSPACE ConfigurationDesk build configuration that compiles CarMaker HIL executables with the Real-Sim libraries. Generated by `scripts/dispatch/5b_carmaker_dspace.ps1` from CarMaker's own `CM_BuildConfig.py`, one per CarMaker / dSPACE version pair in `dependencies.yaml`. +- `patch_user_c.ps1` - Patches the CarMaker project's `User.c` for the Real-Sim integration - `RealSimCarMakerSetup.py` - Prepares CarMaker testrun files for Real-Sim co-simulation. Creates traffic objects and signal synchronization tables for SUMO/CarMaker coordination. - `RealSimSetCarMakerConfig.py` - Parses `config.yaml` and generates CarMaker-specific configuration files for HIL setup @@ -91,8 +91,7 @@ Documentation files including simulator-specific guides: - `CARLAdoc.md` - CARLA interface documentation #### **ProprietaryFiles/** -Proprietary or licensed files not for public distribution. Includes: -- `buildRS_2024a.bat` - Builds Real-Sim MEX files for MATLAB R2024a +Private submodule ([ORNL-Real-Sim/ProprietaryFiles](https://github.com/ORNL-Real-Sim/ProprietaryFiles)) with the CarMaker, VISSIM and dSPACE integration code that cannot be public. Without access it stays empty; the release zip ships the binaries built from it. #### **.github/** GitHub-specific configuration (workflows, issue templates, CI/CD). @@ -252,32 +251,13 @@ The packer refuses to publish a `bin/` whose DLLs do not load, so an incomplete ## Build Scripts -### `compileExternalLibraries.bat` -Compiles required external dependencies: -- **yaml-cpp** - YAML configuration parser library (builds both Release and Debug versions) - -**Requirements:** CMake, Visual Studio 2022 - -**Usage:** -```batch -compileExternalLibraries.bat -``` - -### `dispatch.bat` -Main build dispatcher script for creating release builds. - -**What it does:** -1. Activates `realsimdev` conda environment -2. Runs `dispatchRealSim.py` to orchestrate the complete build process -3. Deactivates conda environment - -**Usage:** -```batch -dispatch.bat -``` - -### `dispatchRealSim.py` -Python orchestration script that automates the complete build process. Compiles all C++ projects using MSBuild, copies executables to `build/` folder, and prepares the release package. +The build is driven by `scripts/dispatch/dispatch.bat`, which initializes the clone +(`scripts/initialize_fixs.ps1`: submodules, native deps, yaml-cpp) and then runs the +numbered component scripts in `scripts/dispatch/` (`1_external_libraries.bat` for +yaml-cpp, `2_core_components.bat` for TrafficLayer, and so on), copying everything to +`build/`. Each component script can also be run on its own. [BUILD.md](BUILD.md) is +the reference for all of it: prerequisites, what each script builds, debug builds, +and the release CI. --- @@ -308,32 +288,24 @@ Utility script to add or modify vehicle message field definitions across the cod ### Initial Setup (For Developers) -1. **Install Prerequisites:** - - Visual Studio 2022 (with C++ development tools) - - CMake (≥3.15) - - Python ≥3.8 - - MATLAB (version depending on your needs: R2019b, R2021b, or R2024a) - -2. **Setup Python Environment:** - ```batch - conda create -n realsimdev python=3.8 - conda activate realsimdev - pip install -r requirements.txt - ``` +1. **Install prerequisites** as listed in [BUILD.md](BUILD.md#prerequisites). The + versions of MATLAB, CarMaker, dSPACE and SUMO come from `dependencies.yaml`. -3. **Compile External Libraries:** +2. **Set up the Python environment:** ```batch - compileExternalLibraries.bat + conda env create -f environment.yml + conda activate realsim ``` -4. **Build Project:** +3. **Build:** ```batch - dispatch.bat + scripts\dispatch\dispatch.bat ``` + Its first step initializes a fresh clone (see + [First-Run Setup](BUILD.md#first-run-setup-fresh-clone)). -5. **Verify Build:** - - Check `build/` folder for executables - - Ensure `TrafficLayer.exe` and simulator-specific DLLs are present +4. **Verify the build:** `build/` holds `TrafficLayer.exe` and the simulator-specific + DLLs, and `build/BUILD_INFO.txt` records what was built. --- @@ -395,9 +367,9 @@ python CarMaker/RealSimSetCarMakerConfig.py --configFile --cm-project-pat ``` #### 4. Build HIL Executable -In dSPACE ConfigurationDesk, run the appropriate build configuration script: -- For MATLAB R2021b: `CarMaker/RS_CM_BuildConfig_r2021b.py` -- For MATLAB R2019b: `CarMaker/RS_CM_BuildConfig_r2019b.py` +In dSPACE ConfigurationDesk, run the build configuration script generated for your +CarMaker / dSPACE versions, e.g. `CarMaker/RS_CM13_1_3_BuildConfig_2024a.py` (see +the CarMaker section under Repository Structure). This configures compiler settings, search paths, and libraries for Real-Sim integration. @@ -492,4 +464,4 @@ For simulator-specific details, see: For general setup and configuration: - [Configuration Guide](ConfigSetup.md) -- [Setup Guide](setupGuide.md) +- [Getting Started](getting-started.md) diff --git a/doc/about.md b/doc/about.md index 6fedebc7..f5cb3210 100644 --- a/doc/about.md +++ b/doc/about.md @@ -1,3 +1,6 @@ # About -Real-Sim develops a multi-resolution X-in-the-loop (XIL) simulation framework to support inclusive testing and evaluation of emerging technologies such as connected and automated vehicles. The Real-Sim framework connects different simulation components and integrates various traffic and vehicle simulation tools, virtual environments, and XIL systems through a Flexible Interface for XIL Simulation (FIXS). Connections among different tools are transparent to users and handled by the interface behind the scenes. Co-simulation of various vehicle and traffic simulation tools with different XIL systems can be easily achieved and become a transparent "plug-and-play" process to users. \ No newline at end of file +```{include} ../README.md +:start-after: "" +:end-before: "" +``` diff --git a/doc/changelog.md b/doc/changelog.md index d1e399ac..bf23c4d7 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -1,11 +1,29 @@ -# Changelog +# Releases -This project’s detailed release history is still being curated. For now, use the summary below to understand the major documentation changes relevant to Read the Docs. +FIXS publishes builds on three rolling channels. Each channel is a GitHub prerelease +that CI re-publishes on every push to its branch, and each has a matching version of +this documentation (pick it in the version menu at the bottom left). -## Unreleased +| Channel | Built from | Docs version | Meant for | +|---|---|---|---| +| `stable` | `main` | `stable` (default) | users | +| `vX.Y.Z-beta` | `beta_vX.Y.Z` | `vX.Y.Z-beta` | testing a release candidate | +| `vX.Y.Z-alpha` | `dev_vX.Y.Z` | `vX.Y.Z-alpha` | development builds | -- Added dedicated stub pages (`getting-started`, `installation`, `usage`, `faq`) to satisfy the Sphinx toctrees. -- Created tutorial placeholders for future step-by-step walkthroughs. -- Added API and changelog placeholders so the main navigation renders cleanly on Read the Docs. +## Downloads -Future releases will expand this page with a full semantic versioning history once documentation updates are finalized. +All builds are on the [GitHub Releases](https://github.com/ORNL-Real-Sim/FIXS/releases) +page. A channel's release carries `fixs-build-.zip` (Windows) and, on the +0.9 trains and later, `fixs-build--linux-x86_64.zip`. Applications install a +build with their own update command (for example `run_cosim.bat --update-fixs`), +which unpacks it with [`scripts/update_fixs.ps1`](../scripts/update_fixs.ps1). + +## Release notes + +Release notes are on each GitHub release. The last fixed-version releases are +[v0.7.0](https://github.com/ORNL-Real-Sim/FIXS/releases/tag/v0.7.0) and +[v0.6.0](https://github.com/ORNL-Real-Sim/FIXS/releases/tag/v0.6.0); 0.9.0 is on the +beta and alpha channels. + +How CI builds and publishes the channels is described in +[BUILD.md](BUILD.md#rolling-release-channels). diff --git a/doc/getting-started.md b/doc/getting-started.md index ccd6a04c..bb16c4ff 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,27 +1,51 @@ # Getting Started -Use this page as the on-ramp into the Real-Sim toolchain. It pulls together the minimum set of steps from the existing guides so you can validate your environment quickly before diving into any of the traffic-simulator-specific docs. +The path from nothing to a first co-simulation, then on to the guide for your +simulator. -## 1. Clone and Initialize +## 1. Get FIXS -1. Clone the repository and update submodules (see `README.md` for any project-specific flags). -2. Review `requirements.txt` together with `doc/setupGuide.md` so you know which external tools (SUMO, CarMaker, MATLAB, etc.) must already be on your workstation. +Either use a published build or build from source. -## 2. Verify Prerequisites +- **Published build:** download `fixs-build-.zip` from + [GitHub Releases](https://github.com/ORNL-Real-Sim/FIXS/releases). The + [Releases](changelog.md) page explains the channels; `stable` is built from `main`. +- **From source:** clone the repository and run `scripts\dispatch\dispatch.bat`. Its + first step initializes a fresh clone (submodules, native dependencies, yaml-cpp). + [BUILD.md](BUILD.md) covers prerequisites, what gets built, and building single + components. -1. Run `env.check.py` from the repo root to check Conda, Python, and the required Python packages. -2. Install any missing traffic simulator binaries (CarMaker, VISSIM, SUMO) following the instructions in their respective docs under `doc/`. +The supported versions of SUMO, CARLA, CarMaker, MATLAB and dSPACE are pinned in +[`dependencies.yaml`](../dependencies.yaml). -## 3. Configure Your First Scenario +## 2. Set up Python -1. Copy one of the provided configs, e.g., `tests\coordMerge\config_SUMO.yaml`. -2. Update IP/port information to match your machine (both Real-Sim’s `TrafficLayer.exe` and the simulator it talks to). -3. If you are targeting SUMO, walk through `doc/SUMOdoc.md`; for VISSIM or CarMaker, follow their corresponding guides. +The Python helpers and example clients use the conda environment defined in +[`environment.yml`](../environment.yml): -## 4. Run a Smoke Test +```batch +conda env create -f environment.yml +conda activate realsim +``` -1. Launch `TrafficLayer.exe -f `. -2. Start the simulator specified in the config. -3. For MATLAB/Simulink workflows, open the provided example model under `CarMaker` or `CommonLib` and confirm the interface connects. +`python env.check.py` checks for conda, SUMO and the required Python packages. If +conda is missing it offers to download and install Miniconda. -Once you can send messages end-to-end, proceed to the Tutorial pages for deeper walkthroughs. +## 3. Run a first example + +[`tests/Python/SimpleEchoClient`](../tests/Python/SimpleEchoClient/) is the smallest +end-to-end setup: SUMO drives a vehicle around a loop, TrafficLayer relays its state, +and a Python client receives it and echoes it back. `run_simple_echo_client.bat` +starts all three in order: SUMO, then TrafficLayer, then the client. It expects +TrafficLayer from a source build (`TrafficLayer\x64\Release`); with a published build, +point it at your `TrafficLayer.exe`. The folder's README describes what you should +see. + +## 4. Next steps + +- [Configuration reference](ConfigSetup.md): every `config.yaml` key. +- Simulator guides: [VISSIM](VISSIMdoc.md), [SUMO](SUMOdoc.md), + [CarMaker](CarMakerDoc.md), [CARLA](CARLAdoc.md). +- When something fails, TrafficLayer writes its errors to `TrafficLayer.err`, and + `EnableVerboseLog: true` in `SimulationSetup` logs the full message flow. See also + the [FAQ](faq.md). diff --git a/doc/index.rst b/doc/index.rst index 98f24ff3..63908ca6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,10 +12,7 @@ Real-Sim Documentation :caption: User Guide getting-started - installation - setupGuide ConfigSetup - usage faq .. toctree:: diff --git a/doc/installation.md b/doc/installation.md deleted file mode 100644 index ca04dcff..00000000 --- a/doc/installation.md +++ /dev/null @@ -1,37 +0,0 @@ -# Installation - -This page collects the cross-cutting install steps referenced throughout the simulator-specific guides. Follow it in sequence, then jump to the tutorial or platform doc that matches your workflow. - -## 1. System Packages - -- **Windows 10/11** with administrator privileges. -- Visual Studio 2022 (Desktop development with C++) for building CarMaker integrations. -- MATLAB/Simulink (version aligned with your CarMaker release; see `doc/CarMakerDoc.md`). -- SUMO, VISSIM, and CarMaker binaries when needed (see their respective docs for supported versions). - -## 2. Python Environment - -```powershell -# from the repo root -python -m venv .venv -.venv\Scripts\activate -pip install -r requirements.txt -``` - -Alternatively, run `env.check.py` to let the project script verify/repair your Conda-based toolchain. - -## 3. Build Helper Libraries - -Some workflows (especially CarMaker) require compiled helper libraries: - -1. Open `VirtualEnvironment/VirtualEnvironment.sln` in Visual Studio. -2. Build Release (and Debug if needed) targets for the `VirtualEnvironment` project. -3. If you need dSPACE support, follow the “Compile dSPACE library” section of `doc/CarMakerDoc.md`. - -## 4. TrafficLayer and Configs - -1. Review the sample configs under `tests/` or `doc/ConfigSetup.md`. -2. Copy a config file and adjust IP/port bindings plus vehicle subscription blocks for your simulator. -3. Keep `TrafficLayer.exe` accessible (either build it yourself or use the shipped binary) and test it with `TrafficLayer.exe -f ` before launching a full simulation. - -After completing these steps, you are ready to move on to the Tutorial pages (`tutorials/quickstart.md` and `tutorials/examples.md`) for simulator-specific walkthroughs. diff --git a/doc/setupGuide.md b/doc/setupGuide.md deleted file mode 100644 index a191db7a..00000000 --- a/doc/setupGuide.md +++ /dev/null @@ -1,99 +0,0 @@ -# Setup Guide - -> Guide for installing, configuring, and running the Real-Sim Environment - ---- - -## Prerequisites - -**System & Hardware** - -- **OS:** Windows 10+ -- **Tools (Versions):** - - Python 3.8+ - - SUMO 1.13.0 - - MATLAB 9.7 - - CarMaker 10.0.1 - - VISSIM 11.0 - -**Python Packages** - -- easydict -- numpy -- pyyaml -- ruamel.yaml -- pandas -- matplotlib -- traci -- sumolib - ---- - -## Installation - -1. Clone the repository. -2. Check `requirements.txt`. -3. Run the `env.check.py` file to install required frameworks and packages. - - This script checks for each required tool, prompts to auto-install, and installs any missing Python packages. -4. Run the program in your IDE. - -Once installation is complete, you should see an output similar to: - -```text -# Successful output message -Succesful Environment Check: - -Environment Setup Script (Windows + Conda) - -Checking if Conda is available... - Conda is available. - - Checking if Python is installed in Conda... - # packages in environment at C:\Users\YourComputer\miniconda3: - # - # Name Version Build Channel - brotli-python 1.0.9 py313h5da7b33_9 - python 3.13.2 hadb2040_100_cp313 - python_abi 3.13 0_cp313 - - Checking if SUMO is installed... - SUMO is installed at: C:\Users\YourComputer\sumo-1.21.0\bin\sumo.EXE - easydict is already installed. - numpy is already installed. - yaml is already installed. - ruamel.yaml is already installed. - pandas is already installed. - matplotlib is already installed. - traci is already installed. - sumolib is already installed. - -Environment Setup check completed. - -``` - -## Running Test Cases - -- **Test script:** `run_experiments.py` -- **Config file:** `ecodrivingConfig_SUMO.yaml` - -See the [Config Setup](ConfigSetup.md) page for test case setup details. - ---- - -## Troubleshooting - -### Missing packages -1. Check `requirements.txt` and run the `env.check.py` script. -2. You should get a confirmation message if all dependencies are installed. -3. If not, manually install missing requirements and rerun the script. -4. Ensure your system meets all prerequisites. - -### Miniconda prompt -- When running `env.check.py`, you may be prompted to download Miniconda. -- Type **Y** and confirm. -- This will install Miniconda and allow Python and SUMO to be set up automatically. - -### Cannot run the script -1. If the script fails, manually install the correct Python version first. -2. Verify all frameworks listed in `requirements.txt` are installed. -3. Rerun `env.check.py` to finalize environment setup. diff --git a/doc/usage.md b/doc/usage.md deleted file mode 100644 index 65ace757..00000000 --- a/doc/usage.md +++ /dev/null @@ -1,32 +0,0 @@ -# Usage - -This page highlights the common workflows once your environment is installed. For detailed simulator steps, keep the SUMO/VISSIM/CarMaker docs nearby. - -## Launch Order - -1. **TrafficLayer** – start from a terminal: `TrafficLayer.exe -f path\to\config.yaml`. -2. **Application layer** – run your MATLAB/Simulink model or other control logic if enabled in the config. -3. **Traffic simulator** – start SUMO, VISSIM, or CarMaker with the matching test case. - -## Editing Configurations - -- `SimulationSetup`: choose the simulator (`SUMO`, `VISSIM`, `CarMaker`) and set `TrafficSimulatorIP/Port`. -- `ApplicationSetup`: subscribe to vehicles (by id or type) and ports for Real-Sim clients. -- `XilSetup`: mirror the relevant subscriptions when doing HIL/dSPACE runs. - -Refer to `doc/ConfigSetup.md` for the full schema and field descriptions. - -## Running Provided Scenarios - -1. Inspect the `tests/` directory for ready-made batch scripts (e.g., `runCoordMergeSUMO.bat`). -2. Update paths inside the script to point at your simulator binaries and config file. -3. Execute the script, then monitor logs under `TrafficLayerLogs/` for handshake status. - -## Collecting Data - -- Enable verbose logging in the YAML (`EnableVerboseLog: true`) to capture full message streams. -- Use the provided Python utilities in `CommonLib` to post-process sensor/vehicle data. - -## Troubleshooting - -See `doc/setupGuide.md` for general issues (missing packages, Conda prompts) and each simulator doc for platform-specific debugging steps. From 5958a12ced8c434e1831b1b2a3ac28e726b3b776 Mon Sep 17 00:00:00 2001 From: yunlishao-vibe <267182001+yunlishao-vibe@users.noreply.github.com> Date: Wed, 23 Sep 2026 18:05:33 -0400 Subject: [PATCH 3/4] docs(#137): one nav entry per page; unpublish internal design docs FIXS_message_flow had six top-level headings, each shown as its own page in the left panel; single_title.py now fails the build on that. The #156 DLL proposal and GUI wireframes stay in the repo but are excluded from the site. --- doc/DEVELOPER_GUIDE.md | 6 ++++++ doc/FIXS_message_flow.md | 10 +++++----- doc/_ext/single_title.py | 25 +++++++++++++++++++++++++ doc/conf.py | 5 ++++- doc/index.rst | 2 -- 5 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 doc/_ext/single_title.py diff --git a/doc/DEVELOPER_GUIDE.md b/doc/DEVELOPER_GUIDE.md index 827c9305..4480b301 100644 --- a/doc/DEVELOPER_GUIDE.md +++ b/doc/DEVELOPER_GUIDE.md @@ -122,6 +122,12 @@ are errors. Writing docs: - A page must be listed in a `toctree` in `doc/index.rst`, or it is built but unreachable. +- One `#` title per page, `##` and below for sections. Every top-level heading becomes + its own entry in the left panel, so `doc/_ext/single_title.py` fails the build on a + second one. +- Internal design documents (e.g. `156_drivingsim_dll_design_proposal.md`, + `gui-design/`) stay in the repo but are listed in `exclude_patterns` in `doc/conf.py`, + so they are not published. - Link repo files outside `doc/` relatively (`../tests/Vissim/Ipg/`), so the link also works on GitHub. On Read the Docs, `doc/_ext/repo_links.py` turns each one into a GitHub link at the commit being built. A link to a file that does not diff --git a/doc/FIXS_message_flow.md b/doc/FIXS_message_flow.md index edf73e61..0ad4a885 100644 --- a/doc/FIXS_message_flow.md +++ b/doc/FIXS_message_flow.md @@ -11,7 +11,7 @@ The figures below illustrate the system architecture and the message flow betwee --- -# 1. Co-Simulation Model Overview +## 1. Co-Simulation Model Overview The following figure shows the overall structure of the co-simulation framework used in this project. It illustrates how the traffic simulation layer, control layer, and high-fidelity vehicle model interact with each other. @@ -20,7 +20,7 @@ It illustrates how the traffic simulation layer, control layer, and high-fidelit --- -# 2. Final model message Flow +## 2. Final model message Flow This figure illustrates the **Final and ideal message flow** for the co-simulation framework. @@ -37,7 +37,7 @@ This design represents the **target architecture** for fully consistent traffic --- -# 3. Current Implementation +## 3. Current Implementation The following diagram shows the **current implementation** used in the project. @@ -58,7 +58,7 @@ For implementation details, please refer to the Python control code. --- -# 4. Baseline Model +## 4. Baseline Model The baseline model represents a simplified configuration used for comparison with the proposed co-simulation framework. @@ -71,7 +71,7 @@ This configuration is used as a **reference case** for evaluating the impact of --- -# Notes +## Notes This document provides a high-level overview of the simulation architecture. More detailed explanations of each component and interface will be added in future updates. \ No newline at end of file diff --git a/doc/_ext/single_title.py b/doc/_ext/single_title.py new file mode 100644 index 00000000..7e0f447e --- /dev/null +++ b/doc/_ext/single_title.py @@ -0,0 +1,25 @@ +"""Warn when a page has more than one top-level heading. + +Each top-level heading becomes its own entry in the navigation, so a page with +several ``#`` headings shows up in the left panel as several pages. Under +``-W`` (RTD fail_on_warning, the docs PR check) the warning fails the build. +""" +from docutils import nodes +from sphinx.util import logging + +logger = logging.getLogger(__name__) + + +def _check(app, doctree): + tops = [n for n in doctree.children if isinstance(n, nodes.section)] + if len(tops) > 1: + logger.warning( + "%d top-level headings (%s); use one '#' title and '##' for sections", + len(tops), ", ".join(repr(t[0].astext()) for t in tops[1:4]), + location=(app.env.docname, tops[1].line), + ) + + +def setup(app): + app.connect("doctree-read", _check) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/doc/conf.py b/doc/conf.py index 8b2c2331..c45256bf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,12 +18,15 @@ "sphinx.ext.napoleon", # Google/NumPy style docstrings "sphinx.ext.viewcode", "repo_links", # links out of doc/ -> GitHub at the built commit + "single_title", # one top-level heading per page (else: extra nav entries) ] repo_links_github = "https://github.com/ORNL-Real-Sim/FIXS" templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# Internal design documents: kept in the repo, not published as reader docs. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", + "156_drivingsim_dll_design_proposal.md", "gui-design/**"] # Recognize both .rst and .md files source_suffix = { diff --git a/doc/index.rst b/doc/index.rst index 63908ca6..0b10dad5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -62,8 +62,6 @@ Real-Sim Documentation DEVELOPER_GUIDE ContributionGuide FIXS_message_flow - gui-design/wireframes - 156_drivingsim_dll_design_proposal .. toctree:: :maxdepth: 2 From c9bee357e20a11fb0d0eacf28a71fcdd33a9f616 Mon Sep 17 00:00:00 2001 From: yunlishao-vibe <267182001+yunlishao-vibe@users.noreply.github.com> Date: Wed, 23 Sep 2026 18:08:58 -0400 Subject: [PATCH 4/4] docs(#137): standard collapsed nav; unpublish the XIL design studies Expand only the page being read, two levels deep. CarlaDynoCoupling and DynoDataChecks describe unbuilt/unrun work and leave the site like the other design docs; links to excluded pages now open them on GitHub. --- doc/DEVELOPER_GUIDE.md | 5 +++-- doc/_ext/repo_links.py | 16 +++++++++++----- doc/conf.py | 7 ++++--- doc/index.rst | 2 -- 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/doc/DEVELOPER_GUIDE.md b/doc/DEVELOPER_GUIDE.md index 4480b301..bf9e3a20 100644 --- a/doc/DEVELOPER_GUIDE.md +++ b/doc/DEVELOPER_GUIDE.md @@ -126,8 +126,9 @@ Writing docs: its own entry in the left panel, so `doc/_ext/single_title.py` fails the build on a second one. - Internal design documents (e.g. `156_drivingsim_dll_design_proposal.md`, - `gui-design/`) stay in the repo but are listed in `exclude_patterns` in `doc/conf.py`, - so they are not published. + `gui-design/`, the XIL design studies) stay in the repo but are listed in `exclude_patterns` in `doc/conf.py`, + so they are not published. A published page may still link to one; the link opens + the file on GitHub. - Link repo files outside `doc/` relatively (`../tests/Vissim/Ipg/`), so the link also works on GitHub. On Read the Docs, `doc/_ext/repo_links.py` turns each one into a GitHub link at the commit being built. A link to a file that does not diff --git a/doc/_ext/repo_links.py b/doc/_ext/repo_links.py index f9e6ea83..354ed212 100644 --- a/doc/_ext/repo_links.py +++ b/doc/_ext/repo_links.py @@ -2,9 +2,10 @@ The pages are also read on GitHub, so they link repo files relatively (``../tests/Vissim/Ipg/``, ``../CLAUDE.md``). Sphinx only builds doc/, so on -Read the Docs those links have no target. This rewrites each one whose target -exists in the repo to a GitHub URL pinned to the commit being built, so every -docs version links the code it was built from. A link whose target does not +Read the Docs those links have no target. The same goes for a link to a page +kept out of the site by ``exclude_patterns`` (internal design documents). This +rewrites each one whose target exists in the repo to a GitHub URL pinned to the +commit being built, so every docs version links the code it was built from. A link whose target does not exist anywhere is left alone, so MyST still warns about it. """ import functools @@ -45,16 +46,21 @@ def run(self, **kwargs): continue if node["refdomain"] == "doc": # MyST already made these relative to doc/ and dropped ".md". + # A built page resolves normally; a .md outside doc/ or one + # left out of the site (exclude_patterns) goes to GitHub. + if node["reftarget"] in self.env.all_docs: + continue target, anchor = node["reftarget"] + ".md", node.get("reftargetid") path = os.path.join(srcdir, target) else: target, _, anchor = unquote(node["reftarget"]).partition("#") refdoc = self.env.doc2path(node.get("refdoc", self.env.docname)) path = os.path.join(os.path.dirname(refdoc), target) + if not os.path.relpath(path, srcdir).startswith(".."): + continue # inside doc/: Sphinx/MyST handle it path = os.path.normpath(path) rel = os.path.relpath(path, repo_root) - outside_doc = os.path.relpath(path, srcdir).startswith("..") - if rel.startswith("..") or not outside_doc or not os.path.exists(path): + if rel.startswith("..") or not os.path.exists(path): continue url = base_url.format( kind="tree" if os.path.isdir(path) else "blob", diff --git a/doc/conf.py b/doc/conf.py index c45256bf..52eaaffe 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -26,7 +26,8 @@ templates_path = ["_templates"] # Internal design documents: kept in the repo, not published as reader docs. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", - "156_drivingsim_dll_design_proposal.md", "gui-design/**"] + "156_drivingsim_dll_design_proposal.md", "gui-design/**", + "xil/CarlaDynoCoupling.md", "xil/DynoDataChecks.md"] # Recognize both .rst and .md files source_suffix = { @@ -48,9 +49,9 @@ #Options for HTML output html_theme = "sphinx_rtd_theme" html_theme_options = { - "collapse_navigation": False, + "collapse_navigation": True, # expand only the page being read "sticky_navigation": True, "includehidden": True, - "navigation_depth": 4, # <-- ensure depth is enough for your nesting + "navigation_depth": 2, # page title + its ## sections } diff --git a/doc/index.rst b/doc/index.rst index 0b10dad5..1cbafc47 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -38,8 +38,6 @@ Real-Sim Documentation :caption: XIL Bench xil/AxleDynoCarMakerCoupling - xil/CarlaDynoCoupling - xil/DynoDataChecks .. toctree:: :maxdepth: 3