Use KaTeX in documentation

[hauleth]

Before:

After:

Close #225

[hauleth]

This PR also allow us to describe whole method used to implement given function, ex.:

[bluss]

Cool. Not to be a super downer, but while docs.rs is awesome, it also makes it so that it's best if docs build well there, so is it possible to use this there? Their maintainer seems pretty open to installing new software and so on, so maybe.

[hauleth]

This requires no additional software, only some environment variable. So if it is possible to set them on docs.rs then it should work.

[cuviper]

It definitely looks nice! But I do have concerns...

• I would prefer all resources stay local, especially for offline use. KaTeX advertises that it is self-contained to allow bundling, so that should be possible.
• The injection is a bit fragile, leaning on an environment variable, and RUSTDOCFLAGS isn't even supported in stable cargo. This also injects into all crates at the time, not just num's.
• This won't work (as-is) for the sub-crates when generated independently. That's important for docs.rs where everything is independent.
• Even from the main crate, it won't work if generated as a dependency in someone else's docs.

I think perhaps it will need some cargo enhancements before this can work cleanly.

[cuviper]

It wouldn't be so bad if it degraded better, but raw math typesetting is really ugly IMO.

[hauleth]

Yeah it is a shame, but currently there is no other way to achieve that. We could although try to propose such change for Cargo.

[hauleth]

However I would love to have possibility to use ASCIIDoc instead of Markdown in documentation as it is more suitable and have a lot more possibilities to work with. Unfortunately that isn't going to happen soon :(

[cuviper]

IMO, the cosmetic improvement when this works right is not enough to justify the problems.
If Cargo can be improved to reliably integrate this, that will probably tip the scales.

[homu]

☔ The latest upstream changes (presumably #246) made this pull request unmergeable. Please resolve the merge conflicts.

[cuviper]

Closing as a stale PR. I'd rather wait for properly integrated support in cargo and/or rustdoc.