chore: update links, faster deploy (#191)

* update links, faster deploy

* fix lint, clippy

* add section about mdbook

.github/workflows/deploy.yml

@@ -29,20 +29,30 @@ jobs:
       MDBOOK_KATEX_VERSION: 0.9.2
     steps:
       - uses: actions/checkout@v4
-      - name: Install mdBook
+
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+
+      - name: Install rust
         run: |
           curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
           rustup update
-          cargo install --version ${MDBOOK_VERSION} mdbook
-          cargo install --version ${MDBOOK_KATEX_VERSION} mdbook-katex
+
+      - name: Install mdbook
+        run: |
+          cargo binstall --no-confirm --version ${MDBOOK_VERSION} mdbook
+          cargo binstall --no-confirm --version ${MDBOOK_KATEX_VERSION} mdbook-katex
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
+
       - name: Build with mdBook
         run: |
           cargo run --bin create_mdbook
           cp -r assets book/
           mdbook build
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -94,6 +94,23 @@ To see computations used in the background, go to the `math/` directory.
 From there, you can run the `.sage` files in a SageMath environment.
 In particular, the `math/field.sage` computes roots of unity in the `PlutoField` which is of size 101. To install sage on your machine, follow the instructions [here](https://doc.sagemath.org/html/en/installation/index.html). If you are on a Mac, you can install it via homebrew with `brew install --cask sage`.
 
+## Building mdBook
+
+To locally build/serve the [mdBook](https://github.com/rust-lang/mdBook) site, install mdBook and [mdbook-katex](https://github.com/lzanini/mdbook-katex):
+```
+cargo install mdbook
+cargo install mdbook-katex
+```
+
+To build, run:
+```
+cargo run --bin create_mdbook
+cp -r assets book/
+mdbook build
+```
+
+If you want to serve locally, run `mdbook serve`.
+
 ## License
 
 Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)

book.toml

@@ -16,5 +16,5 @@ after = ["links"]
 
 [output.html]
 default-theme = "dark"
-preferred-dark-theme = "coal"
+preferred-dark-theme = "ayu"
 git-repository-url = "https://github.com/pluto/ronkathon"

src/algebra/group/README.md

@@ -7,7 +7,7 @@
 - `FiniteCyclicGroup`: a finite group with a generator.
 
 ### `Group`
-[`Group`](./group.rs) represents a group with finite elements. It defines a binary operation on the set of elements of the group.
+[`Group`](./mod.rs) represents a group with finite elements. It defines a binary operation on the set of elements of the group.
 - `IDENTITY`: The identity element of the group.
 - `inverse(&self) -> Self`: inverse of the element.
 - `operation(a: &Self, b: &Self) -> Self`: the operation of the group.
@@ -27,4 +27,4 @@ It uses compile time assertions to check that $P$ is prime.
 
 ## Examples
 
-[PermutationGroup](/examples/permutation_group.rs) example showcases how `Group` trait is implemented for any struct.
+[Symmetric Group](../../../examples/symmetric_group.rs) example showcases how `Group` trait is implemented for any struct.

src/bin/create_mdbook.rs

@@ -1,6 +1,7 @@
-/// Read SUMMARY.md and copy `README.md` files given in it to `book` directory.
-/// Additionally, change the links to other `README.md` files to `index.md`, so that link
-/// points to correct file in the mdbook.
+/// 1. Read SUMMARY.md and copy `README.md` files given in it to `book` directory.
+/// 2. Change the links to other `README.md` files to `index.md`, so that link points to
+///    correct file in the mdbook.
+/// 3. Change links that point to a '.rs' file to their github repo link.
 use std::{
   fs::{self, File},
   io::{self, BufRead, BufReader, Write},
@@ -10,6 +11,8 @@ use std::{
 use regex::Regex;
 
 const DEST: &str = "book";
+const REPO_LINK: &str = "https://github.com/pluto/ronkathon/blob/main/";
+const SHOW_CHANGES: bool = false;
 
 fn main() -> io::Result<()> {
   let dest_path = Path::new(DEST);
@@ -32,9 +35,14 @@ fn main() -> io::Result<()> {
   }
 
   let readme_re = Regex::new(r"README.md").unwrap();
+  let rs_links = Regex::new(r"(?<t>\[.*\])\([/]?(?<l>.*\.rs)\)").unwrap();
 
   for src in &readmes {
     println!("Working on: {}", src.display());
+    let mut src_parent = src.parent().unwrap().to_str().unwrap().to_owned();
+    if !src_parent.is_empty() {
+      src_parent.push('/');
+    }
 
     let dest = Path::new(DEST).join(src);
     let dest_folder = dest.parent().unwrap();
@@ -48,8 +56,15 @@ fn main() -> io::Result<()> {
 
     for line in reader.lines() {
       let before = line.unwrap();
-      let after = readme_re.replace_all(&before, "index.md");
-      dest_file.write_all(after.as_bytes())?;
+      let after1 = readme_re.replace_all(&before, "index.md");
+      if before != after1 && SHOW_CHANGES {
+        println!("1. {before} -> {after1}");
+      }
+      let after2 = rs_links.replace_all(&after1, format!("$t({}{}$l)", REPO_LINK, src_parent));
+      if after1 != after2 && SHOW_CHANGES {
+        println!("2. {after1} -> {after2}");
+      }
+      dest_file.write_all(after2.as_bytes())?;
       dest_file.write_all(b"\n")?;
     }
   }

src/curve/README.md

@@ -14,7 +14,7 @@ Predominantly, we use the extension $F_{p^2}$ since we need this for the [Tate p
 We refer to $F_{101}$ as the `PlutoBaseField` and $F_{101^2}$ as the `PlutoBaseFieldExtension` within `ronkathon`.
 From which, we also use the terminology of `PlutoCurve` to refer to $E(F_{101})$ and `PlutoExtendedCurve` to refer to $E(F_{101^2})$.
 
-We also define a `CurveGroup`, an extension of [`FiniteGroup`](../field/group.rs) trait representing the group law of the curve.
+We also define a `CurveGroup`, an extension of [`FiniteGroup`](../algebra/group/mod.rs) trait representing the group law of the curve.
 
 ### Type B curve and type 1 pairing