Embedding LaTeX in Rust documentation?


#1

Is there any way for us to embed LaTeX code in Rust’s documentation so that the generated documentation renders the LaTeX formatted properly? I’ve used Doxygen’s implementation of this before, with the \f$ [whatever you want formatted here] \f$, but I haven’t been able to find anything like that for Rust’s built in documentation. It would be a shame to have to forgo the built in documentation for something like this, but it is sometimes a pretty important feature for me.

Thanks!


#2

Not currently.


#3

One of my hopes for Tectonic is that we can make this tractable in the Rust ecosystem!

I believe that a motivated person could get something going with the existing code. I have big plans for nice HTML output that will make things even better, though. (The secret plan is to see if I can even get to the point that TeX is a more appealing markup language than Markdown, but we have a loooooong way to go before that happens …)


#4

@pkgw

I’m curious if https://github.com/ReTeX/ReX could be useful in someway. The goal is quite different than Tectonic in that it strives to only extract the most common math mode parts of LaTeX instead of full complience. But perhaps, with a little refactoring, we can share some of the same logic.

I haven’t shared it much because it needs a lot of polishing (it was my first rust project) and ignore the build instructions for now but the ecmascript demo still works.


#5

@cbreeden Wow, neat! I could certainly imagine that ReX might be the better way to go for something like getting math into Markdown documents.

Tectonic does aim to support the complete TeX language in all of its details, and based on my experience with how interconnected the TeX code is, I’m pessimistic about the prospects of being able to share much code with efforts like ReX that aim for (say) 90% coverage. But it would be great to be proved wrong on that front!


#6

Tectonic does aim to support the complete TeX language in all of its details, and based on my experience with how interconnected the TeX code is, I’m pessimistic about the prospects of being able to share much code with efforts like ReX that aim for (say) 90% coverage.

I’m inclined to agree. Nonetheless, the layout algorithms are accurate (like looking into the source of LuaTeX and XeTeX to get it right):

If you ever get to the point where you are looking to implement opentype math layout features like those feel free to take a look.


#7

Why not just use mathjax with markdown to embed LaTeX formulas? I haven’t looked at embedding JavaScript into the generated docs, but for my own uses I’ve found mathjax combined with markdown to be excellent.


#8

Actually came across a comment about this on reddit just a few days ago: https://www.reddit.com/r/rust/comments/6fsy2x/docsrs_now_supports_building_nondefault_features/dikqty0/

The linked pull request ( https://github.com/rust-num/num/pull/226 ) should have what you need to use KaTeX in your documentation (though I guess you should also use rustdoc-args to get it working on docs.rs as shown in the OP link )