Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Migrate to Docusaurus #1836

Closed
wants to merge 4 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 23 additions & 94 deletions .github/workflows/book.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,114 +12,43 @@ on:
- "book/**"
merge_group:

jobs:
# test:
# runs-on: ubuntu-latest
# name: test
# timeout-minutes: 60

# steps:
# - uses: actions/checkout@v4

# - name: Install mdbook
# run: |
# mkdir mdbook
# curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
# echo $(pwd)/mdbook >> $GITHUB_PATH

# - name: Install mdbook-template
# run: |
# mkdir mdbook-template
# curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
# echo $(pwd)/mdbook-template >> $GITHUB_PATH

# - name: Run tests
# run: mdbook test

lint:
runs-on: ubuntu-latest
name: lint
timeout-minutes: 60

steps:
- uses: actions/checkout@v4

- name: Install mdbook-linkcheck
run: |
mkdir mdbook-linkcheck
curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck
echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH

- name: Run linkcheck
run: mdbook-linkcheck --standalone
defaults:
run:
working-directory: book

jobs:
build:
name: Build Docusaurus
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@nightly
- name: Install mdbook
run: |
mkdir mdbook
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
echo $(pwd)/mdbook >> $GITHUB_PATH

- name: Install mdbook-template
run: |
mkdir mdbook-template
curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
echo $(pwd)/mdbook-template >> $GITHUB_PATH

- uses: Swatinem/rust-cache@v2
with:
cache-on-failure: true

- name: Build book
run: mdbook build
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 18
cache: npm
cache-dependency-path: book/package-lock.json

# - name: Build docs
# run: cargo docs
# env:
# # Keep in sync with ./ci.yml:jobs.docs
# RUSTDOCFLAGS:
# --cfg docsrs --show-type-layout --generate-link-to-definition --enable-index-page
# -Zunstable-options
- name: Install dependencies
run: npm ci

# - name: Move docs to book folder
# run: |
# mv target/doc target/book/docs
- name: Create New Code Refrences
run: chmod +x gen-code-refs.sh && ./gen-code-refs.sh

- name: Archive artifact
shell: sh
run: |
chmod -c -R +rX "target/book" |
while read line; do
echo "::warning title=Invalid file permissions automatically fixed::$line"
done
tar \
--dereference --hard-dereference \
--directory "target/book" \
-cvf "$RUNNER_TEMP/artifact.tar" \
--exclude=.git \
--exclude=.github \
.
- name: Build website
run: npm run build

- name: Upload artifact
uses: actions/upload-artifact@v4
- name: Upload Build Artifact
uses: actions/upload-pages-artifact@v3
with:
name: github-pages
path: ${{ runner.temp }}/artifact.tar
retention-days: 1
if-no-files-found: error
path: book/build

deploy:
# Only deploy if a push to main
if: github.ref_name == 'main' && github.event_name == 'push'
# if: github.ref_name == 'main' && github.event_name == 'push'
runs-on: ubuntu-latest
needs: [lint, build]
needs: [build]

# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
permissions:
Expand All @@ -135,4 +64,4 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
uses: actions/deploy-pages@v4
30 changes: 30 additions & 0 deletions .github/workflows/test-book.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Test deployment

on:
pull_request:
branches: [main, dev]

defaults:
run:
working-directory: book

jobs:
test-deploy:
name: Test doc build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: actions/setup-node@v4
with:
node-version: 18
cache: npm
cache-dependency-path: book/package-lock.json

- name: Install dependencies
run: npm ci

- name: Test build website
run: npm run build
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ pgo-data.profdata
**/proof-with-io.bin
**/program.bin
**/stdin.bin
**/node_modules

# Benchmark
benchmark.csv
Expand All @@ -37,4 +38,4 @@ crates/prover/vk

# Example fibonacci groth16 / plonk proofs
examples/fibonacci/fibonacci-groth16.bin
examples/fibonacci/fibonacci-plonk.bin
examples/fibonacci/fibonacci-plonk.bin
20 changes: 20 additions & 0 deletions book/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
41 changes: 41 additions & 0 deletions book/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

Using SSH:

```
$ USE_SSH=true yarn deploy
```

Not using SSH:

```
$ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
77 changes: 0 additions & 77 deletions book/SUMMARY.md

This file was deleted.

File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
@@ -1,23 +1,22 @@
import Compressed from "../../static/examples_fibonacci_script_bin_compressed.rs.mdx";
import Execute from "../../static/examples_fibonacci_script_bin_execute.rs.mdx";

# Advanced Usage

## Execution Only

We recommend that during the development of large programs (> 1 million cycles) you do not generate proofs each time.
Instead, you should have your script only execute the program with the RISC-V runtime and read `public_values`. Here is an example:

```rust,noplayground
{{#include ../../examples/fibonacci/script/bin/execute.rs}}
```
<Execute />

If the execution of your program succeeds, then proof generation should succeed as well! (Unless there is a bug in our zkVM implementation.)

## Compressed Proofs

With the `ProverClient`, the default `prove` function generates a proof that is succinct, but can have size that scales with the number of cycles of the program. To generate a compressed proof of constant size, you can use the `prove_compressed` function instead. This will use STARK recursion to generate a proof that is constant size (around 7Kb), but will be slower than just calling `prove`, as it will use recursion to combine the core SP1 proof into a single constant-sized proof.

```rust,noplayground
{{#include ../../examples/fibonacci/script/bin/compressed.rs}}
```
<Compressed />

You can run the above script with `RUST_LOG=info cargo run --bin compressed --release` from `examples/fibonacci/script`.

Expand All @@ -27,7 +26,7 @@ You can use `utils::setup_logger()` to enable logging information respectively.

**Logging:**

```rust,noplayground
```rust
utils::setup_logger();
```

Expand Down Expand Up @@ -55,7 +54,7 @@ sp1-sdk = { version = "2.0.0", features = ["neon"] }

For maximal performance, you should run proof generation with the following command and vary your `shard_size` depending on your program's number of cycles.

```rust,noplayground
```rust
SHARD_SIZE=4194304 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
```

Expand All @@ -64,6 +63,6 @@ SHARD_SIZE=4194304 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --re
To reduce memory usage, set the `SHARD_BATCH_SIZE` environment variable depending on how much RAM
your machine has. A higher number will use more memory, but will be faster.

```rust,noplayground
```rust
SHARD_BATCH_SIZE=1 SHARD_SIZE=2097152 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
```
Loading
Loading