Update structure for miden-book

.github/workflows/book.yml

@@ -1,30 +1,75 @@
-name: miden book
+# Performs checks, builds and deploys the documentation mdbook.
+#
+# Flow is based on the official github and mdbook documentation:
+#
+#   https://github.com/actions/starter-workflows/blob/main/pages/mdbook.yml
+#   https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions
 
+name: book
+
+# Documentation should be built and tested on every pull-request, and additionally deployed on push onto next.
 on:
+  workflow_dispatch:
+  pull_request:
+    path: ['docs/**']
   push:
-    branches: [main, next]
+    branches: [next]
+    path: ['docs/**']
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 
 jobs:
-  deploy:
-    name: Deploy miden-vm mdbook
+  # Always build and test the mdbook documentation whenever the docs folder is changed.
+  #
+  # The documentation is uploaded as a github artifact IFF it is required for deployment i.e. on push into next.
+  build:
+    name: Build documentation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
-      - name: Install katex, alerts and linkcheck
-        run: |
-          rustup update --no-self-update stable
-          cargo +stable install mdbook-katex mdbook-linkcheck mdbook-alerts
 
-      - name: Setup mdBook
-        uses: peaceiris/actions-mdbook@v1
+      # Installation from source takes a fair while, so we install the binaries directly instead.
+      - name: Install mdbook and plugins
+        uses: taiki-e/install-action@v2
         with:
-          mdbook-version: "latest"
+          tool: mdbook, mdbook-linkcheck, mdbook-alerts, mdbook-katex
 
-      - name: Build miden book
+      - name: Build book
         run: mdbook build docs/
 
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+      # Only Upload documentation if we want to deploy (i.e. push to next).
+      - name: Setup Pages
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload book artifact
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/book/html
+          # We specify multiple [output] sections in our book.toml which causes mdbook to create separate folders for each. This moves the generated `html` into its own `html` subdirectory.
+          path: ./docs/book/html
+
+  # Deployment job only runs on push to next.
+  deploy:
+    name: Deploy documentation
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -22,3 +22,6 @@ stdlib/assets/std.masl
 
 # Zed
 .zed/
+
+# mdBook
+book/

Makefile

@@ -44,9 +44,9 @@ lint: format fix clippy ## Runs all linting tasks at once (Clippy, fixing, forma
 doc: ## Generates & checks documentation
 	$(WARNINGS) cargo doc ${ALL_FEATURES_BUT_ASYNC} --keep-going --release
 
-.PHONY: mdbook
-mdbook: ## Generates mdbook documentation
-	mdbook build docs/
+.PHONY: book
+book: ## Builds the book & serves documentation site
+	mdbook serve --open docs
 
 # --- testing -------------------------------------------------------------------------------------
 

docs/book.toml

@@ -1,17 +1,16 @@
 [book]
-authors = []
-language = "en"
+authors      = ["Miden contributors"]
+description  = "Documentation for the Miden STARK-based virtual machine"
+language     = "en"
 multilingual = false
-src = "src"
-title = "Polygon Miden VM"
+title        = "The Miden virtual machine"
 
 [output.html]
-git-repository-url = "https://github.com/0xPolygonMiden/miden-vm/"
+git-repository-url = "https://github.com/0xPolygonMiden/miden-vm"
 
 [preprocessor.katex]
 after = ["links"]
 
 [preprocessor.alerts]
 
 [output.linkcheck]
-warning-policy = "ignore"

docs/src/EXPORTED.md

@@ -0,0 +1,53 @@
+<!-- This file is used to represent aggregate documentation for the Miden book -->
+
+# Summary
+
+- [Virtual Machine](./intro/main.md)
+  - [Overview](./intro/overview.md)
+  - [Usage](./intro/usage.md)
+  - [Performance](./intro/performance.md)
+  - [Development tooling](./tools/main.md)
+    - [Debugger](./tools/debugger.md)
+    - [REPL](./tools/repl.md)
+  - [User Documentation](./user_docs/main.md)
+    - [Miden Assembly](./user_docs/assembly/main.md)
+      - [Code Organization](./user_docs/assembly/code_organization.md)
+      - [Execution contexts](./user_docs/assembly/execution_contexts.md)
+      - [Flow Control](./user_docs/assembly/flow_control.md)
+      - [Field Operations](./user_docs/assembly/field_operations.md)
+      - [u32 Operations](./user_docs/assembly/u32_operations.md)
+      - [Stack manipulation](./user_docs/assembly/stack_manipulation.md)
+      - [Input / Output Operations](./user_docs/assembly/io_operations.md)
+      - [Cryptographic Operations](./user_docs/assembly/cryptographic_operations.md)
+      - [Events](./user_docs/assembly/events.md)
+      - [Debugging](./user_docs/assembly/debugging.md)
+    - [Miden Standard Library](./user_docs/stdlib/main.md)
+      - [std::collections](./user_docs/stdlib/collections.md)
+      - [std::crypto::dsa](./user_docs/stdlib/crypto/dsa.md)
+      - [std::crypto::fri](./user_docs/stdlib/crypto/fri.md)
+      - [std::crypto::hashes](./user_docs/stdlib/crypto/hashes.md)
+      - [std::math::u64](./user_docs/stdlib/math/u64.md)
+      - [std::mem](./user_docs/stdlib/mem.md)
+      - [std:sys](./user_docs/stdlib/sys.md)
+  - [Design](./design/main.md)
+    - [Programs](./design/programs.md)
+    - [Program decoder](./design/decoder/main.md)
+      - [Decoder constraints](./design/decoder/constraints.md)
+    - [Operand stack](./design/stack/main.md)
+      - [Operation constraints](./design/stack/op_constraints.md)
+      - [System operations](./design/stack/system_ops.md)
+      - [Field operations](./design/stack/field_ops.md)
+      - [u32 operations](./design/stack/u32_ops.md)
+      - [Stack manipulation](./design/stack/stack_ops.md)
+      - [Input / output operations](./design/stack/io_ops.md)
+      - [Cryptographic operations](./design/stack/crypto_ops.md)
+    - [Range Checker](./design/range.md)
+    - [Chiplets](./design/chiplets/main.md)
+      - [Hash Chiplet](./design/chiplets/hasher.md)
+      - [Bitwise Chiplet](./design/chiplets/bitwise.md)
+      - [Memory Chiplet](./design/chiplets/memory.md)
+      - [Kernel ROM Chiplet](./design/chiplets/kernel_rom.md)
+    - [Lookup arguments](./design/lookups/main.md)
+      - [Multiset checks](./design/lookups/multiset.md)
+      - [LogUp](./design/lookups/logup.md)
+  - [Background Material](./background.md)

docs/src/SUMMARY.md

@@ -1,3 +1,5 @@
+<!-- This file is used to represent local documentation -->
+
 # Summary
 
 - [Introduction](./intro/main.md)