Skip to content

[DOCS] Fix ReadTheDocs coverage: TOC gaps, Python autodoc, stale references #137

@yunlishao-vibe

Description

@yunlishao-vibe

Task Summary

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

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)
  • Remove or add Carla_0915_Windows_Fixes — currently orphaned (not in TOC, unreachable on RTD)
  • Verify all files listed in index.rst actually exist

2. Fix stale references in DEVELOPER_GUIDE.md

  • References RS_CM_BuildConfig_r2021b.py, RS_CM_BuildConfig_r2019b.py, RealSimCarMakerSetup.py — these filenames no longer match the repo
  • 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)
  • Update CommonLib section to reflect removal of MathLibrary.h (unused), 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. 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)

Acceptance Criteria

  • RTD build passes with no warnings on missing files
  • 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions