-
Notifications
You must be signed in to change notification settings - Fork 5
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Milestone
Description
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
devbranch
Scope of Work
1. Fix index.rst TOC
- Add
BUILDto 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.rstactually 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.mdstub with properautomoduledirectives - Verify
sphinx.ext.autodocandsphinx.ext.napoleonproduce 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 PRsabout.md(2 lines) — expand with project mission, funding, affiliationsusage.md(32 lines) — expand with real launch examplestutorials/quickstart.md,tutorials/examples.md— add minimal working examples usingtests/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.rstdoc/DEVELOPER_GUIDE.mddoc/api/index.md→ replace with autodoc.rstfilesdoc/changelog.md,doc/about.md,doc/usage.mddoc/tutorials/quickstart.md,doc/tutorials/examples.mdCommonLib/*.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.mdappears in RTD navigation - Python API reference renders real content (not "forthcoming" stub)
- DEVELOPER_GUIDE references match actual filenames in repo
- No orphaned
.mdfiles outside the TOC
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation