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