[DOCS] ReadTheDocs: fix TOC/autodoc/stale refs + auto-build on main #137

Task Summary

Wire up Python autodoc, fix broken/orphaned TOC entries, add missing BUILD.md to navigation, update stale file references in DEVELOPER_GUIDE, stub out thin placeholder pages with real content, and set up automatic RTD builds when main is updated.

Branch and PR Target

• All PRs for this issue should target the dev branch

Scope of Work

1. Fix index.rst TOC

• Add BUILD to the Development section (currently not linked despite being the most useful developer reference)
• Fix broken mdinclude: index.rst starts with .. mdinclude:: README.md, but there is no doc/README.md — the include target is missing, so the landing page intro either silently drops or errors depending on the resolver. Point it at the repo-root README (../README.md) or add a doc/README.md.
• Orphaned pages — stale: every page under doc/ is now in a toctree (the Carla build guides sit under Building from Source); Sphinx reports no orphans.
• Verify all files listed in index.rst actually exist
• Note: CARLAdoc.md is correctly linked (as CARLAdoc); an earlier internal note calling it orphaned was stale.

2. Fix stale references in DEVELOPER_GUIDE.md

• References RS_CM_BuildConfig_r2021b.py, RS_CM_BuildConfig_r2019b.py — these no longer exist (the BuildConfig files are now generated by 5b_carmaker_dspace.ps1). RealSimCarMakerSetup.py does still exist.
• Update to reflect current CarMaker build scripts (RS_CM11_1_2_BuildConfig_2024a.py, RS_CM13_1_3_BuildConfig_2024a.py, patch_user_c.ps1)
• CommonLib removals — stale: MathLibrary.h is still in the repo (listed as legacy), and the guide never mentioned RealSimCmHelper / ryml_all.hpp.

3. Wire Python autodoc

Now that CommonLib/__init__.py exists (PR #133), autodoc can generate real API pages:

• Add docstrings to CommonLib/ConfigHelper.py, MsgHelper.py, SocketHelper.py, VehDataMsgDefs.py
• Replace doc/api/index.md stub with proper automodule directives
• Verify sphinx.ext.autodoc and sphinx.ext.napoleon produce clean output on RTD build

4. Fill thin placeholder pages

These are in the TOC but nearly empty:

• changelog.md (11 lines) — add real version history from git tags / merged PRs
• about.md (2 lines) — expand with project mission, funding, affiliations
• usage.md (32 lines) — expand with real launch examples
• tutorials/quickstart.md, tutorials/examples.md — add minimal working examples using tests/Python/SimpleEchoClient

5. Automatic RTD builds on main update (new)

Currently RTD builds are not automatically triggered when main advances, so the hosted docs drift from the released code. Wire up automatic rebuilds:

• RTD side: confirm the project's Git integration/webhook is connected to ORNL-Real-Sim/FIXS. If the RTD ↔ GitHub webhook is present and active, pushes to a configured branch already trigger builds — audit whether it exists and is healthy first.
• Branch/version config: ensure the main branch (and/or stable/latest versions) is active in RTD project settings so it actually builds and publishes on push. Decide which RTD version maps to main (release docs) vs dev (development docs).
• Fallback if webhook is unavailable (e.g. org perms block the RTD GitHub App): add a lightweight GitHub Actions workflow on push: [main] that calls the RTD Build API (POST /api/v3/projects/<slug>/versions/<ver>/builds/ with an RTD API token stored as a repo secret) to trigger the build. This also cleanly extends to auto-building on dev.
• Document the chosen mechanism (webhook vs Actions + Build API) in DEVELOPER_GUIDE.md so maintainers know how docs get published.
• Housekeeping: the config file is .readthedocs.yml (v2 schema, ubuntu-22.04, python 3.11). RTD prefers .readthedocs.yaml — optional rename for convention. sphinx.fail_on_warning is currently false; consider flipping to true once the TOC/autodoc warnings above are cleared so future drift fails the build.

6. Defer: C++ Doxygen API

C++ headers (ConfigHelper.h, SocketHelper.h, MsgHelper.h, TrafficHelper.h) have zero Doxygen comments. Adding breathe+exhale now would generate empty pages. This should be a follow-on issue once doc comments are added to the headers.

Files Involved

• doc/index.rst
• doc/DEVELOPER_GUIDE.md
• doc/api/index.md → replace with autodoc .rst files
• doc/changelog.md, doc/about.md, doc/usage.md
• doc/tutorials/quickstart.md, doc/tutorials/examples.md
• CommonLib/*.py (docstrings)
• doc/conf.py (if autodoc config needs updating)
• doc/requirements_doc.txt (no new deps needed for autodoc)
• .readthedocs.yml (optional rename + fail_on_warning)
• .github/workflows/ (new — only if webhook fallback is needed)

Acceptance Criteria

• RTD build passes with no warnings on missing files
• index.rst landing-page intro renders (mdinclude target resolves)
• BUILD.md appears in RTD navigation
• Python API reference renders real content (not "forthcoming" stub)
• DEVELOPER_GUIDE references match actual filenames in repo
• No orphaned .md files outside the TOC
• A push to main automatically triggers and publishes an RTD build (verified with a test push)
• The docs-publishing mechanism is documented in DEVELOPER_GUIDE.md