Skip to content

Commit de3dc47

Browse files
phklivebobbinth
phklive
authored and
bobbinth
committed
chore: update structure for miden-book (#1716)
1 parent 80e8143 commit de3dc47

File tree

7 files changed

+127
-26
lines changed

7 files changed

+127
-26
lines changed

‎.github/workflows/book.yml

+61-16
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,75 @@
1-
name: miden book
1+
# Performs checks, builds and deploys the documentation mdbook.
2+
#
3+
# Flow is based on the official github and mdbook documentation:
4+
#
5+
# https://github.com/actions/starter-workflows/blob/main/pages/mdbook.yml
6+
# https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions
27

8+
name: book
9+
10+
# Documentation should be built and tested on every pull-request, and additionally deployed on push onto next.
311
on:
12+
workflow_dispatch:
13+
pull_request:
14+
path: ['docs/**']
415
push:
5-
branches: [main, next]
16+
branches: [next]
17+
path: ['docs/**']
18+
19+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
20+
permissions:
21+
contents: read
22+
pages: write
23+
id-token: write
24+
25+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
26+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
27+
concurrency:
28+
group: "pages"
29+
cancel-in-progress: false
630

731
jobs:
8-
deploy:
9-
name: Deploy miden-vm mdbook
32+
# Always build and test the mdbook documentation whenever the docs folder is changed.
33+
#
34+
# The documentation is uploaded as a github artifact IFF it is required for deployment i.e. on push into next.
35+
build:
36+
name: Build documentation
1037
runs-on: ubuntu-latest
1138
steps:
1239
- uses: actions/checkout@main
13-
- name: Install katex, alerts and linkcheck
14-
run: |
15-
rustup update --no-self-update stable
16-
cargo +stable install mdbook-katex mdbook-linkcheck mdbook-alerts
1740

18-
- name: Setup mdBook
19-
uses: peaceiris/actions-mdbook@v1
41+
# Installation from source takes a fair while, so we install the binaries directly instead.
42+
- name: Install mdbook and plugins
43+
uses: taiki-e/install-action@v2
2044
with:
21-
mdbook-version: "latest"
45+
tool: mdbook, mdbook-linkcheck, mdbook-alerts, mdbook-katex
2246

23-
- name: Build miden book
47+
- name: Build book
2448
run: mdbook build docs/
2549

26-
- name: Deploy to GitHub Pages
27-
uses: peaceiris/actions-gh-pages@v3
50+
# Only Upload documentation if we want to deploy (i.e. push to next).
51+
- name: Setup Pages
52+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
53+
id: pages
54+
uses: actions/configure-pages@v5
55+
56+
- name: Upload book artifact
57+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
58+
uses: actions/upload-pages-artifact@v3
2859
with:
29-
github_token: ${{ secrets.GITHUB_TOKEN }}
30-
publish_dir: ./docs/book/html
60+
# 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.
61+
path: ./docs/book/html
62+
63+
# Deployment job only runs on push to next.
64+
deploy:
65+
name: Deploy documentation
66+
environment:
67+
name: github-pages
68+
url: ${{ steps.deployment.outputs.page_url }}
69+
runs-on: ubuntu-latest
70+
needs: build
71+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
72+
steps:
73+
- name: Deploy to GitHub Pages
74+
id: deployment
75+
uses: actions/deploy-pages@v4

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,6 @@ stdlib/assets/std.masl
2222

2323
# Zed
2424
.zed/
25+
26+
# mdBook
27+
book/

‎Makefile

+3-3
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,9 @@ lint: format fix clippy ## Runs all linting tasks at once (Clippy, fixing, forma
4444
doc: ## Generates & checks documentation
4545
$(WARNINGS) cargo doc ${ALL_FEATURES_BUT_ASYNC} --keep-going --release
4646

47-
.PHONY: mdbook
48-
mdbook: ## Generates mdbook documentation
49-
mdbook build docs/
47+
.PHONY: book
48+
book: ## Builds the book & serves documentation site
49+
mdbook serve --open docs
5050

5151
# --- testing -------------------------------------------------------------------------------------
5252

‎docs/.gitignore

-1
This file was deleted.

‎docs/book.toml

+5-6
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
[book]
2-
authors = []
3-
language = "en"
2+
authors = ["Miden contributors"]
3+
description = "Documentation for the Miden STARK-based virtual machine"
4+
language = "en"
45
multilingual = false
5-
src = "src"
6-
title = "Polygon Miden VM"
6+
title = "The Miden virtual machine"
77

88
[output.html]
9-
git-repository-url = "https://github.com/0xPolygonMiden/miden-vm/"
9+
git-repository-url = "https://github.com/0xPolygonMiden/miden-vm"
1010

1111
[preprocessor.katex]
1212
after = ["links"]
1313

1414
[preprocessor.alerts]
1515

1616
[output.linkcheck]
17-
warning-policy = "ignore"

‎docs/src/EXPORTED.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<!-- This file is used to represent aggregate documentation for the Miden book -->
2+
3+
# Summary
4+
5+
- [Virtual Machine](./intro/main.md)
6+
- [Overview](./intro/overview.md)
7+
- [Usage](./intro/usage.md)
8+
- [Performance](./intro/performance.md)
9+
- [Development tooling](./tools/main.md)
10+
- [Debugger](./tools/debugger.md)
11+
- [REPL](./tools/repl.md)
12+
- [User Documentation](./user_docs/main.md)
13+
- [Miden Assembly](./user_docs/assembly/main.md)
14+
- [Code Organization](./user_docs/assembly/code_organization.md)
15+
- [Execution contexts](./user_docs/assembly/execution_contexts.md)
16+
- [Flow Control](./user_docs/assembly/flow_control.md)
17+
- [Field Operations](./user_docs/assembly/field_operations.md)
18+
- [u32 Operations](./user_docs/assembly/u32_operations.md)
19+
- [Stack manipulation](./user_docs/assembly/stack_manipulation.md)
20+
- [Input / Output Operations](./user_docs/assembly/io_operations.md)
21+
- [Cryptographic Operations](./user_docs/assembly/cryptographic_operations.md)
22+
- [Events](./user_docs/assembly/events.md)
23+
- [Debugging](./user_docs/assembly/debugging.md)
24+
- [Miden Standard Library](./user_docs/stdlib/main.md)
25+
- [std::collections](./user_docs/stdlib/collections.md)
26+
- [std::crypto::dsa](./user_docs/stdlib/crypto/dsa.md)
27+
- [std::crypto::fri](./user_docs/stdlib/crypto/fri.md)
28+
- [std::crypto::hashes](./user_docs/stdlib/crypto/hashes.md)
29+
- [std::math::u64](./user_docs/stdlib/math/u64.md)
30+
- [std::mem](./user_docs/stdlib/mem.md)
31+
- [std:sys](./user_docs/stdlib/sys.md)
32+
- [Design](./design/main.md)
33+
- [Programs](./design/programs.md)
34+
- [Program decoder](./design/decoder/main.md)
35+
- [Decoder constraints](./design/decoder/constraints.md)
36+
- [Operand stack](./design/stack/main.md)
37+
- [Operation constraints](./design/stack/op_constraints.md)
38+
- [System operations](./design/stack/system_ops.md)
39+
- [Field operations](./design/stack/field_ops.md)
40+
- [u32 operations](./design/stack/u32_ops.md)
41+
- [Stack manipulation](./design/stack/stack_ops.md)
42+
- [Input / output operations](./design/stack/io_ops.md)
43+
- [Cryptographic operations](./design/stack/crypto_ops.md)
44+
- [Range Checker](./design/range.md)
45+
- [Chiplets](./design/chiplets/main.md)
46+
- [Hash Chiplet](./design/chiplets/hasher.md)
47+
- [Bitwise Chiplet](./design/chiplets/bitwise.md)
48+
- [Memory Chiplet](./design/chiplets/memory.md)
49+
- [Kernel ROM Chiplet](./design/chiplets/kernel_rom.md)
50+
- [Lookup arguments](./design/lookups/main.md)
51+
- [Multiset checks](./design/lookups/multiset.md)
52+
- [LogUp](./design/lookups/logup.md)
53+
- [Background Material](./background.md)

‎docs/src/SUMMARY.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
<!-- This file is used to represent local documentation -->
2+
13
# Summary
24

35
- [Introduction](./intro/main.md)

0 commit comments

Comments
 (0)