proposal: go/doc: Add LaTeX support in documentation via MathJax

[chewxy]

Motivation

Say you have a function that implements an equation found in a paper. You would ideally want to put the equation in the documentation (as well as a link to the paper) for quick referencing.

It also makes documentation of math based code more complete in godoc, without having to fly all over the place to look for it.

Proposal

I propose MathJax be supported in godoc when godoc generates html files. The html files godoc generates currently uses JS anyway - MathJax is a one-file dependency can can just be dropped in.

The "lean"est possible support for LaTeX is to leverage the block parser in comment.go. This also means that I'm proposing we start with just block LaTeX and not support inline LaTeX yet.

Currently go/doc has a very simple parser for blocks - indentations are parsed with indentLine and applies opPre to the block. I'm suggesting adding opLaTeX as an op as well, by using backticks(`) to delimit LaTeX inputs. This adds a trivial amount of complexity, for a big gain in documentation presentation.

Example

Note the backticks that signify the beginning and end of the LaTeX block

// Softmax is a generalization of a logistic function blahblahblah....
//
//		`\sigma(z)_j = \frac{e^{z_j}}{\sum_{k=1}^{K} e^{z_j}}`
func Softmax(...){}

Generating HTML

When it comes to file renders, simply add a new case to ToHTML, and wrap the block in $$...$$. No need to run emphasize() on it.

Possible Downsides / Points of Contentions

Slippery Slope Argument

Per #7873, @bradfitz pointed out that it may be a slippery slope to suddenly supporting markdown. However, I would like to argue that LaTeX support is quite necessary. Most python libraries that deal with math and machine learning related stuff have math equations strewn in them in the documentation, and it helps developers understand the code better.

MathJax is Apache2.0

IANAL, can't comment much on this topic. The Go community by and large have a preference for MIT/BSD-like licences, so I suspect the Apache2.0 licence of MathJax may be an issue.

Equations have no place in code documentation

I would like to argue otherwise. Often, the equations are the clarifying factor for the functions/methods.

People will abuse LaTeX in their documentation!!oneone11!

I think that's their problem. This can be partially negated by only supporting LaTeX blocks and not inline LaTeX. You can't do much with a block of LaTeX. Plus LaTeX is pretty tedious to write, so there isn't much abuse I suspect.

Related Issue

• x/tools/cmd/godoc: request for richer formatting #16666

[minux]

I'd argue that given the full Unicode support, you can already
write simple equations in code (and you can even use greek
alphabet in variable names, e.g. golang.org/x/image/vector.)

The problem is that, most Go code doesn't need this capability,
so supporting LaTeX will have less audience than supporting
Markdown. To put it another way, if LaTeX support is necessary,
then Markdown support will be even more necessary. As a
concrete example, in the standard library, I think only the
math/* packages and some of crypto/* packages might benefit
from LaTeX support. But nearly every package could benefit
from markdown support (see how many places bullet points
are used, for example.)

[chewxy]

Well if you look at it, many scientific computing related libraries already sneak LaTeX in them (example). If only godoc could render them. Furthermore, many more (like this) would have more easy-to-read documentation with LaTeX in godoc html, don't you agree?.

Adding LaTeX support will definitely court the scientific computing people to Go as a platform.

[dominikh]

At the risk of making a slippery slope argument, but: Where do we stop? Sequence diagrams would be nice, the subset of actually useful parts of UML might be nice. And, just like LaTeX, none of those would look right in some of the non-browser environment, such as the go doc command in a terminal.

[chewxy]

I'd argue that sequence diagram/uml should be put into a library's README, because they are mostly architectural decisions/rationales whereas I consider LaTeX (specifically the equations) to be documentation of a function or method.

Yes, we can currently write equations as comments in mostly unicode, but some of the more complex equations often go beyond one line (I used softmax as an example above).

Also, LaTeX is kinda readable in a non-browser env, but just barely (and for more complicated ones not at all)

[bradfitz]

I agree with Minux. Unicode is probably sufficient for what we usually need.

I'm going to decline this. If we're not going to add Markdown support, we're definitely not going to add support for this. Especially because it relies on either an external CDN service to render, or a ton of code that isn't written in Go.