Issue description

I was digging around in the awesome Go bindings and came across a very strange issue:

https://www.mlpack.org/doc/mlpack-3.2.2/python_documentation.html#gmm_probability_detailed-documentation

The table right there doesn't make sense. It comes from this source Markdown:

This program calculates the probability that given points came
from a given GMM (that is, P(X | gmm)).  The GMM is specified
with the `InputModel` parameter, and the points are specified
with the `Input` parameter.  The output probabilities may be
saved via the `Output` output parameter.

So, for example, to calculate the probabilities of each point in
`points` coming from the pre-trained GMM `gmm`, while storing
those probabilities in `probs`, the following command could be used:

The issue here is the P(X | gmm)! How unexpected.

That source Markdown is generated by the Markdown bindings, in src/mlpack/bindings/markdown/. Those bindings, to create the documentation, call out to the binding generators for all the other languages (CLI, Python, Julia).

Your environment

• version of mlpack: mlpack-git (any version with Markdown bindings is affected)
• operating system: Linux
• compiler: gcc
• version of dependencies (Boost/Armadillo): (not relevant)
• any other environment information you think is relevant:

Steps to reproduce

1. Clone the repository.
2. Configure CMake with -DBUILD_MARKDOWN_BINDINGS=ON.
3. make markdown
4. Take a look in doc/mlpack.md to find the weird Markdown bit with the "GMM probability" binding. Maybe there are some other bindings.

Expected behavior

Ideally, the website shouldn't show this documentation as a table.

Actual behavior

https://www.mlpack.org/doc/mlpack-3.2.2/python_documentation.html#gmm_probability_detailed-documentation

Steps towards a solution

There are a handful of ways we can solve this, but changing the | to \| or something in the PROGRAM_INFO() in src/mlpack/methods/gmm_probability_main.cpp (which is where that documentation string comes from) isn't a good approach, since that will display incorrectly for non-Markdown bindings.

So, I see a couple of ways forward...

1. Modify the Kramdown processing on mlpack.org (see the mlpack/mlpack.org repository) so that it doesn't just accidentally make a table out of this. That's probably the easiest thing? But then this issue is filed in the wrong repository (oops).

2. Make it so that any time programInfo.documentation() is called from any function in src/mlpack/bindings/markdown/, any instances of | are properly escaped (assuming that escaping works with Kramdown). Note that in src/mlpack/bindings/markdown/, any functions just call out to different bindings languages.

There's not a need to "claim" the issue by asking if you can work on it. Just work on it, and open a PR when you believe you've fixed the issue, and then we can go from there.

(I might find some time to fix this in the relatively near future, but it's not guaranteed, so I thought I would open an issue for it...)