Merge pull request #299 from 0xPolygonMiden/bitwalker/docs-restructuring

docs: switch from mdbook to mkdocs
0xPolygonMiden · Sep 2, 2024 · 305ea1c · 305ea1c
2 parents 99f3802 + 8e29842
commit 305ea1c
Show file tree

Hide file tree

Showing 18 changed files with 129 additions and 87 deletions.
diff --git a/Makefile.toml b/Makefile.toml
@@ -259,38 +259,35 @@ install_crate = { crate_name = "litcheck", test_arg = "--help" }
 [tasks.book]
 category = "Build"
 description = "Builds the compiler documentation"
-dependencies = ["mdbook", "mdbook-linkcheck", "mdbook-alerts"]
-command = "mdbook"
-args = ["build", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/docs"]
-
-[tasks.mdbook]
-category = "Build"
-install_crate = { crate_name = "mdbook", binary = "mdbook", test_arg = [
-    "--help",
-] }
-
-[tasks.mdbook-linkcheck]
-category = "Build"
-install_crate = { crate_name = "mdbook-linkcheck" }
-
-[tasks.mdbook-alerts]
-category = "Build"
-install_crate = { crate_name = "mdbook-alerts" }
+command = "docs/mkdocs"
+args = ["build", "-d", "target/docs/site"]
 
 [tasks.serve-book]
 category = "Build"
 description = "Opens the compiler documentation"
-install_crate = { crate_name = "mdbook", binary = "mdbook", test_arg = [
-    "--help",
-] }
-command = "mdbook"
-args = ["serve", "--open", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/docs"]
+command = "docs/mkdocs"
+args = ["serve"]
+
+[tasks.mkdocs]
+category = "Documentation"
+description = "Run the mkdocs command-line tool"
+command = "docs/mkdocs"
+args = ["${@}"]
 
 [tasks.clippy]
 description = "Runs clippy on the workspace"
 category = "Development"
 command = "cargo"
-args = ["clippy", "--all", "--all-targets", "--", "-D", "clippy::all", "-D", "warnings"]
+args = [
+    "clippy",
+    "--all",
+    "--all-targets",
+    "--",
+    "-D",
+    "clippy::all",
+    "-D",
+    "warnings",
+]
 dependencies = ["install-clippy"]
 
 [tasks.install-clippy]

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1 @@
-book
+venv
diff --git a/docs/README.md b/docs/README.md
@@ -1,8 +1,8 @@
 # Miden Compiler Docs
 
-This directory contains the sources for the [Miden Compiler Documentation](https://0xpolygonmiden.github.io/compiler/).
+This directory contains the sources for the [Miden Compiler Documentation](https://docs.polygon.technology/miden/compiler/).).
 
-All doc files are written in Markdown, and are converted into an online book using the [mdBook](https://github.com/rust-lang/mdBook) utility.
+All doc files are written in Markdown, and are converted into an online book using [mkdocs](https://squidfunk.github.io/mkdocs-material/).
 
 # License
 

diff --git a/docs/src/appendix/calling_conventions.md → docs/appendix/calling_conventions.md b/docs/src/appendix/calling_conventions.md → docs/appendix/calling_conventions.md
diff --git a/docs/src/assets/.gitkeep → docs/assets/.gitkeep b/docs/src/assets/.gitkeep → docs/assets/.gitkeep
diff --git a/docs/book.toml b/docs/book.toml
diff --git a/docs/src/design/frontends.md → docs/design/frontends.md b/docs/src/design/frontends.md → docs/design/frontends.md
diff --git a/docs/src/design/overview.md → docs/design/overview.md b/docs/src/design/overview.md → docs/design/overview.md
diff --git a/docs/src/guides/develop_miden_in_rust.md → docs/guides/develop_miden_in_rust.md b/docs/src/guides/develop_miden_in_rust.md → docs/guides/develop_miden_in_rust.md
diff --git a/...llup_accounts_and_note_scripts_in_rust.md → ...llup_accounts_and_note_scripts_in_rust.md b/...llup_accounts_and_note_scripts_in_rust.md → ...llup_accounts_and_note_scripts_in_rust.md
diff --git a/docs/src/guides/rust_to_wasm.md → docs/guides/rust_to_wasm.md b/docs/src/guides/rust_to_wasm.md → docs/guides/rust_to_wasm.md
diff --git a/docs/src/guides/wasm_to_masm.md → docs/guides/wasm_to_masm.md b/docs/src/guides/wasm_to_masm.md → docs/guides/wasm_to_masm.md
diff --git a/docs/src/getting_started.md → docs/index.md b/docs/src/getting_started.md → docs/index.md
@@ -1,11 +1,11 @@
 # Getting Started
 
-This book attempts to provide a thorough reference for compiling to Miden Assembly 
-using one or more components of the Miden compiler suite. Which components you use, 
+This page attempts to provide a thorough reference for compiling to Miden Assembly
+using one or more components of the Miden compiler suite. Which components you use,
 and how you use them is likely to differ depending on the project, but we've tried
-to provide good coverage regardless. 
+to provide good coverage regardless.
 
-There are a set of guides which are focused on documenting the workflows for specific 
+There are a set of guides which are focused on documenting the workflows for specific
 use cases that we wish to ensure are well supported, or have encountered so far, but
 if you feel there is anything missing, feel free to open an issue and we will try to
 address the missing docs as soon as possible!
@@ -16,7 +16,7 @@ There are three ways you might use the Miden compiler:
 
 
 1. As an executable (via `midenc`)
-2. As a library (most likely via the `midenc-compile` and `midenc-hir` crates) 
+2. As a library (most likely via the `midenc-compile` and `midenc-hir` crates)
 3. As a Cargo extension (via `cargo miden`)
 
 Each of these is described in the following chapters, we hope you find this book useful!
diff --git a/docs/mkdocs b/docs/mkdocs
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "${@}"
+
+python3 -m venv target/docs/venv
+source target/docs/venv/bin/activate
+pip3 install -r docs/requirements.txt
+mkdocs "${@}"
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs-material==9.5.33
+markdown-include==0.8.1
+mkdocs-open-in-new-tab==1.0.3
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
diff --git a/docs/src/usage/midenc.md → docs/usage/midenc.md b/docs/src/usage/midenc.md → docs/usage/midenc.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,89 @@
+site_name: Miden Compiler Docs
+theme:
+  name: material
+  features:
+    - search.suggest
+    - search.highlight
+    - search.share
+    # - navigation.instant
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.integration
+    #- navigation.tabs
+    #- navigation.tabs.sticky
+    - navigation.indexes
+    #- navigation.sections
+    - navigation.path
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - content.code.copy
+    - content.action.edit
+
+nav:
+  - Getting Started: index.md
+  - Usage:
+      - midenc: usage/midenc.md
+      - cargo miden: usage/cargo-miden.md
+  - Guides:
+      - Rust To WebAssembly: guides/rust_to_wasm.md
+      - WebAssembly To Miden Assembly: guides/wasm_to_masm.md
+      - Developing Miden Programs In Rust: guides/develop_miden_in_rust.md
+      - Developing Miden Rollup Accounts And Note Scripts In Rust: guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md
+  - Compiler Architecture:
+      - Overview: design/overview.md
+      - Frontends: design/frontends.md
+      #- HIR:
+      #- Code Generation:
+      #- Testing:
+  - Appendices:
+      - Calling Conventions: appendix/calling_conventions.md
+
+markdown_extensions:
+  - toc:
+      permalink: true
+      permalink_title: Link to this section
+      toc_depth: 4
+  - codehilite
+  - markdown_include.include:
+      base_path: src
+  - admonition
+  - footnotes
+  - def_list
+  - attr_list
+  - abbr
+  - pymdownx.tabbed
+  - pymdownx.superfences
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.keys
+  - pymdownx.details
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - pymdownx.caret
+  - meta
+  - smarty
+  - pymdownx.extra
+
+plugins:
+  - search
+  - open-in-new-tab
+
+validation:
+  absolute_links: warn
+
+extra_javascript:
+  - https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?version=4.8.0
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
+
+extra_css:
+  - https://fonts.googleapis.com/icon?family=Material+Icons
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css