Fix example and documentation rendering (0xPolygonZero#1614)

* Fix starky runnable doc example and fix cargo doc * Formatting and Clippy * bump katex version and add config.toml * Update README for local doc and add flag for docs.rs * Add missing whitespace --------- Co-authored-by: Robin Salen <[email protected]> Co-authored-by: Ben <[email protected]>
gear-tech · Aug 29, 2024 · a4efbe8 · a4efbe8
1 parent 9fdf1b8
commit a4efbe8
Show file tree

Hide file tree

Showing 9 changed files with 149 additions and 243 deletions.
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -0,0 +1,2 @@
+[build]
+rustdocflags = ["--html-in-header", ".cargo/katex-header.html"]
diff --git a/.cargo/katex-header.html b/.cargo/katex-header.html
@@ -1,10 +1,10 @@
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css"
-    integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js"
-    integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz"
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css"
+    integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"
+    integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg"
     crossorigin="anonymous"></script>
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js"
-    integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI"
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js"
+    integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk"
     crossorigin="anonymous"></script>
 <script>
     document.addEventListener("DOMContentLoaded", function () {

diff --git a/README.md b/README.md
@@ -60,6 +60,14 @@ static GLOBAL: Jemalloc = Jemalloc;
 
 Jemalloc is known to cause crashes when a binary compiled for x86 is run on an Apple silicon-based Mac under [Rosetta 2](https://support.apple.com/en-us/HT211861). If you are experiencing crashes on your Apple silicon Mac, run `rustc --print target-libdir`. The output should contain `aarch64-apple-darwin`. If the output contains `x86_64-apple-darwin`, then you are running the Rust toolchain for x86; we recommend switching to the native ARM version.
 
+## Documentation
+
+Generate documentation locally:
+
+```sh
+cargo doc --no-deps --open
+```
+
 ## Contributing guidelines
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

diff --git a/plonky2/.cargo/config.toml b/plonky2/.cargo/config.toml
@@ -0,0 +1,2 @@
+[build]
+rustdocflags = ["--html-in-header", ".cargo/katex-header.html"]
diff --git a/plonky2/Cargo.toml b/plonky2/Cargo.toml
@@ -87,6 +87,7 @@ harness = false
 # Display math equations properly in documentation
 [package.metadata.docs.rs]
 rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"]
+cargo-args = ["--no-deps"]
 
 [lints]
 workspace = true
diff --git a/plonky2/src/gates/coset_interpolation.rs b/plonky2/src/gates/coset_interpolation.rs
@@ -45,16 +45,16 @@ use crate::util::serialization::{Buffer, IoResult, Read, Write};
 /// non-routed wires. Let $x[]$ be the domain points, $v[]$ be the values, $w[]$ be the Barycentric
 /// weights and $z$ be the evaluation point. Define the sequences
 ///
-/// $p[0] = 1,$
+/// $p\[0\] = 1,$
 ///
-/// $p[i] = p[i - 1] \cdot (z - x[i - 1]),$
+/// $p\[i\] = p[i - 1] \cdot (z - x[i - 1]),$
 ///
-/// $e[0] = 0,$
+/// $e\[0\] = 0,$
 ///
-/// $e[i] = e[i - 1] ] \cdot (z - x[i - 1]) + w[i - 1] \cdot v[i - 1] \cdot p[i - 1]$
+/// $e\[i\] = e[i - 1] ] \cdot (z - x[i - 1]) + w[i - 1] \cdot v[i - 1] \cdot p[i - 1]$
 ///
-/// Then $e[N]$ is the final interpolated value. The non-routed wires hold every $(d - 1)$'th
-/// intermediate value of $p$ and $e$, starting at $p[d]$ and $e[d]$, where $d$ is the gate degree.
+/// Then $e\[N\]$ is the final interpolated value. The non-routed wires hold every $(d - 1)$'th
+/// intermediate value of $p$ and $e$, starting at $p\[d\]$ and $e\[d\]$, where $d$ is the gate degree.
 #[derive(Clone, Debug, Default)]
 pub struct CosetInterpolationGate<F: RichField + Extendable<D>, const D: usize> {
     pub subgroup_bits: usize,

diff --git a/starky/.cargo/config.toml b/starky/.cargo/config.toml
@@ -0,0 +1,2 @@
+[build]
+rustdocflags = ["--html-in-header", ".cargo/katex-header.html"]
diff --git a/starky/Cargo.toml b/starky/Cargo.toml
@@ -36,6 +36,7 @@ env_logger = { version = "0.9.0", default-features = false }
 # Display math equations properly in documentation
 [package.metadata.docs.rs]
 rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"]
+cargo-args = ["--no-deps"]
 
 [lints]
 workspace = true
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		[build]
		rustdocflags = ["--html-in-header", ".cargo/katex-header.html"]