Skip to content

Add LaTeX formatting to doc comments #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 30, 2025
Merged

Conversation

jbangelo
Copy link
Collaborator

@jbangelo jbangelo commented Apr 21, 2025

There are a few places where a bit of LaTeX would help make things a bit more clear in our documentation. Indeed the C library documentation has several uses of LaTeX which Doxygen handles. This is based on the rustdoc-katex-demo crate, which demonstates how to include a link to the KaTex code in the HTML generated for the documents.

Example

The coord documentation has been changed from this
image
to
image
And the helmert transformation docs is now hopefully a bit more clear with the transformation formula fully displayed
image

@jbangelo jbangelo force-pushed the jbangelo/latex-formatting branch from d25c76c to e0d5b31 Compare April 21, 2025 21:27
@jbangelo jbangelo requested a review from Copilot April 21, 2025 21:28
Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This pull request enhances documentation clarity by introducing LaTeX formatting to doc comments and adding KaTeX support for HTML-rendered docs.

  • Updated transformation documentation in swiftnav/src/reference_frame/mod.rs with LaTeX equations
  • Reformatted the CRC polynomial in swiftnav/src/edc.rs and coordinate conversion formulas in swiftnav/src/coords.rs
  • Configured Cargo.toml and added katex-header.html to support math rendering on docs.rs

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
swiftnav/src/reference_frame/mod.rs Updated doc comments for Helmert transformation with LaTeX formatting
swiftnav/src/edc.rs Reformatted CRC polynomial comment using LaTeX delimiters
swiftnav/src/coords.rs Updated coordinate conversion formulas to use LaTeX notation
swiftnav/Cargo.toml Added docs.rs metadata for KaTeX header inclusion
katex-header.html Added KaTeX header with required CSS and JS includes
Comments suppressed due to low confidence (1)

swiftnav/src/reference_frame/mod.rs:144

  • The word 'tranformation' appears to be misspelled; it should be 'transformation'.
/// 3 dimensional rotation, and a universal scaling. The tranformation takes the form of:

Copy link

@pcrumley pcrumley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I dont quite understand the change of the description of the helmert transform and I don't know if they are equivalent e.g. 7 parameters vs 15

# This tells docs.rs to include the katex header for math formatting
# To do this locally
[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "katex-header.html" ]

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

newline 🤓

Comment on lines +8 to +11
{left: "$$", right: "$$", display: true},
{left: "\\(", right: "\\)", display: false},
{left: "$", right: "$", display: false},
{left: "\\[", right: "\\]", display: true}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do overlapping rules work here? Would the
{left: "$", right: "$", display: false}
supersede the
{left: "$$", right: "$$", display: true}

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not entirely sure, this was some boiler plate from the Katex crate. Looking at the original Katex docs it looks like ordering here does matter, and this is the correct ordering to allow $$ to take precedence over $.

@jbangelo jbangelo merged commit 38d76ed into master Apr 30, 2025
6 checks passed
@jbangelo jbangelo deleted the jbangelo/latex-formatting branch April 30, 2025 20:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants