Merge pull request #202 from rust-ndarray/katex-doc

Display math formulas in document by KaTeX

Author: termoshtt

Cargo.toml

@@ -61,3 +61,5 @@ harness = false
 name = "eigh"
 harness = false
 
+[package.metadata.docs.rs]
+rustdoc-args = ["--html-in-header", "katex-header.html"]

README.md

@@ -77,3 +77,22 @@ extern crate ndarray;
 extern crate ndarray_linalg;
 extern crate openblas_src; // or another backend of your choice
 ```
+
+Generate document with KaTeX
+------------------------------
+
+You need to set `RUSTDOCFLAGS` explicitly:
+
+```shell
+RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps
+```
+
+This **only** works for `--no-deps` build because `katex-header.html` does not exists for dependent crates.
+If you wish to set `RUSTDOCFLAGS` automatically in this crate, you can put [.cargo/config](https://doc.rust-lang.org/cargo/reference/config.html):
+
+```toml
+[build]
+rustdocflags = ["--html-in-header", "katex-header.html"]
+```
+
+But, be sure that this works only for `--no-deps`. `cargo doc` will fail with this `.cargo/config`.

katex-header.html

@@ -0,0 +1,16 @@
+<!-- This file includes the work that is distributed in MIT or Apache-2.0 license at https://github.com/paulkernfeld/rustdoc-katex-demo -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"                  integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"    integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe" crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "\\(", right: "\\)", display: false},
+                {left: "$", right: "$", display: false},
+                {left: "\\[", right: "\\]", display: true}
+            ]
+        });
+    });
+</script>