Fix equation rendering in Sphinx docs (closes #8)#14
Merged
Conversation
Sphinx 9 defaults to MathJax v4, which changed the skipHtmlClass/processHtmlClass interaction. myst-parser's update_mathjax adds mathjax_ignore to content sections and relies on processHtmlClass to still render math nodes — this mechanism works correctly in MathJax v3 but not v4. Pin to MathJax v3 and add an explicit mathjax3_config with the correct tex delimiters and processHtmlClass setting. Fixes #8 https://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C
Replace the plain-text 'Formulas:' section with proper RST '.. math::' display directives and ':math:' inline roles, matching the pattern used in the safety metric docstrings. Previously the formulas rendered as raw text in the Sphinx API docs. https://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C
Replace plain-text formula representations in all five trajectory quality metric docstrings with proper RST '.. math::' display directives and ':math:' inline roles: - PathLength: PL sum formula - PathSmoothness: PS normalized sum formula - CurvatureChange: CC and κ_i formulas - AbsoluteTrajectoryError: ATE mean distance formula - RelativeTrajectoryError: RTE relative motion formula https://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C
… as LaTeX Replace plain-text formula representations with proper RST '.. math::' display directives and ':math:' inline roles. Also add r-string prefix to docstrings so LaTeX backslashes are not misinterpreted. https://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C
AmeyaWagh
changed the title
Split the PS formula across two lines in the .. math:: block to stay within the 100-character line length limit. https://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mathjax3_configwith display math settings andprocessHtmlClass.. math::directives and:math:inline roles across all metric docstringsRoot Cause
Two separate issues caused equations not to render:
MathJax v4 incompatibility (
docs/source/conf.py): Sphinx 9 loads MathJax v4 by default. myst-parser'supdate_mathjaxmechanism addsmathjax_ignoreto content sections and relies onoptions.processHtmlClassto still render<div class="math">nodes inside them. This works in MathJax v3 but breaks in v4. Fixed by pinning to MathJax v3.Plain-text formulas in docstrings: Several metric classes used a plain
Formulas:block or bare ASCII math (e.g.SR = N_success / N_total) instead of RST math directives. Sphinx does not render these as LaTeX.Files Changed
docs/source/conf.pymathjax3_configtask_performance/success_rate.py.. math::task_performance/task_completion_rate.py.. math::task_performance/action_accuracy.pyFormulas:block →.. math::directivestrajectory_quality/path_length.py.. math::trajectory_quality/path_smoothness.py.. math::trajectory_quality/curvature_change.py.. math::trajectory_quality/absolute_trajectory_error.py.. math::trajectory_quality/relative_trajectory_error.py.. math::Test Plan
python -m sphinx docs/source docs/build/html -b htmldocs/build/html/index.html— verify all equations in the Metrics Reference section render as formatted math_autosummary/robometric_frame.task_performance.action_accuracy.html) — verify inline and display equations render correctlyhttps://claude.ai/code/session_014kBSLuJ9WpuxuQm9vbtm3C