[yunlishao-vibe]

Summary

Read the Docs (https://real-sim.readthedocs.io) had not built since 2026-04-10. main moved 609 commits after that with no build, and stable was still serving v0.7.0 content. The GitHub webhook delivers fine (every delivery answers 200) and a manual build through the RTD API succeeds, so builds work but pushes had stopped producing them. latest and stable were rebuilt by hand (#34726811, #34726835).

This PR makes the docs build clean, fails any PR that breaks them, rebuilds each release channel's docs when the channel is published, and cleans up the user-facing pages that had gone stale.

Versions follow the release channels

Branch	RTD version
main	stable (default)
beta_vX.Y.Z	vX.Y.Z-beta
dev_vX.Y.Z	vX.Y.Z-alpha

These are the tags release.yml already publishes, so the docs carry the same name as the release zip. The new docs-publish job runs after build-publish under the same condition as linux-publish. It asks RTD to build the version named after the channel tag, and syncs and retries while RTD catches up with a recreated tag. It fails loudly if RTD won't build that version, and warns and passes when there is no RTD_TOKEN secret.

Clean build

The build went from 31 warnings to 0, and .readthedocs.yml now sets fail_on_warning: true.

• Landing page: index.rst used mdinclude, which no installed extension provides, so the README intro was silently dropped. It now includes the README's About section, bounded by comment markers.
• Links out of doc/: these work on GitHub but had no target on RTD. doc/_ext/repo_links.py rewrites each link whose target exists into a GitHub URL at the built commit (READTHEDOCS_GIT_COMMIT_HASH). Links to missing files still fail the build.
• Real defects fixed at the source: a wrong anchor, a %2F-encoded path, two links going up one directory too many, a Routes.yaml link pointing at nothing, heading levels, trailing --- rules, an unknown lexer, and a tab inside a YAML example.
• Version string: release comes from READTHEDOCS_VERSION_NAME instead of the hardcoded 0.10.

PR check

.github/workflows/docs.yml builds the site with -W --keep-going on Python 3.11 on every PR into dev, main, dev_v* and beta_v*. It has no path filter on purpose: docs link into the whole repo.

User pages

• User Guide menu: now Getting Started, Configuration, FAQ. Installation, Usage and Setup Guide repeated the same path with drifted facts:

  • a TrafficLayerLogs/ folder that doesn't exist
  • CarMaker/RealSimGeneric.mdl and CM11_proj (moved or gone)
  • SUMO 1.13 / CarMaker 10 / VISSIM 11
  • a launch order that contradicts the maintained runner

  Getting Started is now the one path: published build or dispatch.bat → environment.yml → SimpleEchoClient → simulator guides.

• Changelog stub → Releases: channels, which docs version matches each, downloads, and where the release notes live (GitHub Releases).

• About: included from the README (contacts, funding, team, presentations), so the README stays the single source.

• Stale build references:

  • Script names: 4a_/4b_/5_mex → 5a_/5b_/6_ in BUILD, CarMakerDoc, README and CLAUDE.md.
  • BuildConfig generation: attributed to 5b_carmaker_dspace.ps1 (where the code actually is).
  • DEVELOPER_GUIDE: nonexistent scripts replaced (compileExternalLibraries.bat, dispatchRealSim.py, RS_CM_BuildConfig_r20xxb.py, buildRS_2024a.bat). Its build section now points to BUILD.md instead of repeating it.
  • Channel tables: BUILD's table still mapped main → latest.

Left panel

• FIXS_message_flow.md had six top-level headings, so each section showed up in the left panel as a separate page. It now has one title with ## sections. doc/_ext/single_title.py fails the build on a second top-level heading; tested against the unfixed page, it flagged that page and no other.
• The [MAINTENANCE] Investigate VISSIM DrivingSimulator.dll and design CarMaker-VISSIM sync workflow #156 DrivingSimulatorProxy design proposal and the GUI wireframes are internal design documents. They stay in the repo, but are removed from the navigation and excluded from the site via exclude_patterns.
• The two XIL design studies (CARLA–dyno coupling, checks to run on dyno data), which describe work not yet built or run, are unpublished the same way. The CarMaker coupling page, which documents the working bench, stays. Links from published pages to excluded ones open the file on GitHub.
• The menu now expands only the page being read, two levels deep (collapse_navigation: True, navigation_depth: 2). Before, every page's sections were expanded, four levels deep.

Related Issues

Part of #137 (issue text corrected where it was out of date). Follow-up: Python autodoc with CommonLib docstrings, and tutorials rebuilt on tests/Python/SimpleEchoClient and verified by running them.

Environment

• Python version: 3.12 (WSL Ubuntu 24.04) with the pinned doc/requirements_doc.txt (Sphinx 7.4.7, myst-parser 2.0.0); RTD's own PR preview build also passed with fail_on_warning on.

Checklist

• Code compiles/runs as expected
• Tests pass locally
• Documentation is updated (if applicable)
• Issue linked above

Verification

• Build: -W --keep-going exits 0. With READTHEDOCS_GIT_COMMIT_HASH=deadbeef, links come out as github.com/ORNL-Real-Sim/FIXS/{blob,tree}/deadbeef/.... The landing intro and the About include both render, and the rest of the README does not leak in.
• Negative control: a temporary [x](../no_such_dir/) fails the -W build with exit 1. An existing ../tests/ link next to it was rewritten.
• docs-publish script, run against the real RTD API:
  • no token → warning, exit 0
  • missing version → HTTP 404 → error, exit 1
  • latest → build triggered, exit 0
• Preview: https://real-sim--395.org.readthedocs.build/en/395/

Done outside the diff

• RTD: default version is stable (site root redirects to /en/stable/), latest is hidden, PR previews are on, and an automation rule activates vX.Y.Z-alpha|beta tags as they are created.
• RTD_TOKEN repo secret set.
• Deleted the dead webhook to the removed RTD project sarayu-reddy (404 on every push).
• Deleted the stale latest git tag, which had no release; stable replaced it on main. It pointed at 2c60d97fe938ac6b24863c544df9b4cdf91c449a if it's ever needed back.

Additional Notes

Locally, Windows Python 3.10 crashes intermittently inside docutils while building. WSL and RTD are unaffected. This is noted in DEVELOPER_GUIDE.