Skip to content

Commit

Permalink
docs: convert core and prover docs to mdbook project and add CI
Browse files Browse the repository at this point in the history
  • Loading branch information
antonbaliasnikov committed Oct 30, 2024
1 parent 42f177a commit 9785095
Show file tree
Hide file tree
Showing 194 changed files with 532 additions and 1 deletion.
67 changes: 67 additions & 0 deletions .github/workflows/deploy-core-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
name: Deploy core docs

on:
push:
branches:
- "main"
tags:
- "core-v*.*.*"
paths:
- 'docs/**'
- '.github/workflows/deploy-core-docs.yml'
pull_request:
paths:
- 'docs/**'
- '.github/workflows/deploy-core-docs.yml'
workflow_dispatch:
inputs:
ref:
description: "Branch, tag or commit to deploy the core docs. If empty, use the ref that triggered the workflow."
required: false
default: ""
version:
type: string
description: "Version of the documentation to deploy"
required: false
default: "latest"

# 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-core-docs:
runs-on: ubuntu-latest
permissions:
contents: write
env:
DOCS_DIR: 'docs'
PROJECT: 'core'
ENABLE_TESTS: false
steps:
- name: Checkout
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
with:
ref: ${{ inputs.ref || '' }}

- name: Extract version from tag
if: startsWith(github.ref, 'refs/tags/')
id: extract-version
shell: 'bash -ex {0}'
run: |
TAG="${{ github.ref_name }}"
VERSION="${TAG#*-}"
echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
- name: Deploy core docs
uses: matter-labs/deploy-mdbooks@77856145362bf23834f2e54a44a928790c4bee7c # v1
with:
version: ${{ inputs.version || steps.extract-version.outputs.version || github.ref_name }}
docs-dir: ${{ env.DOCS_DIR }}
github-token: ${{ secrets.GITHUB_TOKEN }}
enable-tests: ${{ env.ENABLE_TESTS }}
project: ${{ env.PROJECT }}
deploy: ${{ github.event_name != 'pull_request' }}
67 changes: 67 additions & 0 deletions .github/workflows/deploy-prover-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
name: Deploy prover docs

on:
push:
branches:
- "main"
tags:
- "prover-v*.*.*"
paths:
- 'prover/docs/**'
- '.github/workflows/deploy-prover-docs.yml'
pull_request:
paths:
- 'prover/docs/**'
- '.github/workflows/deploy-prover-docs.yml'
workflow_dispatch:
inputs:
ref:
description: "Branch, tag or commit to deploy the prover docs. If empty, use the ref that triggered the workflow."
required: false
default: ""
version:
type: string
description: "Version of the documentation to deploy"
required: false
default: "latest"

# 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-prover-docs:
runs-on: ubuntu-latest
permissions:
contents: write
env:
DOCS_DIR: 'prover/docs'
PROJECT: 'prover'
ENABLE_TESTS: false
steps:
- name: Checkout
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
with:
ref: ${{ inputs.ref || '' }}

- name: Extract version from tag
if: startsWith(github.ref, 'refs/tags/')
id: extract-version
shell: 'bash -ex {0}'
run: |
TAG="${{ github.ref_name }}"
VERSION="${TAG#*-}"
echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
- name: Deploy prover docs
uses: matter-labs/deploy-mdbooks@77856145362bf23834f2e54a44a928790c4bee7c # v1
with:
version: ${{ inputs.version || steps.extract-version.outputs.version || github.ref_name }}
docs-dir: ${{ env.DOCS_DIR }}
github-token: ${{ secrets.GITHUB_TOKEN }}
enable-tests: ${{ env.ENABLE_TESTS }}
project: ${{ env.PROJECT }}
deploy: ${{ github.event_name != 'pull_request' }}
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
book
27 changes: 27 additions & 0 deletions docs/book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
[book]
authors = ["ZKsync team"]
language = "en"
multilingual = false
src = "src"
title = "ZKsync Era Documentation"

[output.html]
smart-punctuation = true
mathjax-support = true
git-repository-url = "https://github.com/matter-labs/zksync-era/tree/main/docs"
edit-url-template = "https://github.com/matter-labs/zksync-era/tree/main/docs/{path}"
additional-js = ["js/version-box.js"]
additional-css = ["css/version-box.css"]

[output.html.playground]
editable = true
line-numbers = true

[output.html.search]
limit-results = 20
use-boolean-and = true
boost-title = 2
boost-hierarchy = 2
boost-paragraph = 1
expand = true
heading-split-level = 2
46 changes: 46 additions & 0 deletions docs/css/version-box.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
#version-box {
display: flex;
align-items: center;
margin-right: 15px; /* Space from the right side */
background-color: transparent; /* Make the box background transparent */
}

/* Base styles for the version selector */
#version-selector {
background-color: transparent; /* Remove background color */
border: 1px solid #4a5568; /* Subtle border */
border-radius: 4px; /* Rounded edges */
padding: 5px 10px; /* Padding inside dropdown */
font-size: 0.9em;
font-weight: normal;
outline: none; /* Removes default focus outline */
cursor: pointer;
}

/* Text color for dark themes */
.theme-navy #version-selector,
.theme-coal #version-selector {
color: #f7fafc; /* Light text color for dark backgrounds */
}

/* Text color for light theme */
.theme-light #version-selector {
color: #333333; /* Dark text color for light background */
}

/* Hover effect for better user feedback */
#version-selector:hover {
background-color: rgba(255, 255, 255, 0.1); /* Light hover effect */
}

/* Optional: Style for when the selector is focused */
#version-selector:focus {
border-color: #63b3ed; /* Accent color for focused state */
}

.right-buttons {
display: flex;
flex-direction: row; /* Aligns items in a row, left to right */
align-items: center; /* Centers items vertically */
gap: 10px; /* Adds space between items */
}
61 changes: 61 additions & 0 deletions docs/js/version-box.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
document.addEventListener("DOMContentLoaded", function() {
// Get the base URL from the mdBook configuration
const baseUrl = document.location.origin + '/zksync-era/core';

// Function to create version selector
function createVersionSelector(versions) {
const versionSelector = document.createElement("select");
versionSelector.id = "version-selector";

// Get the current path
const currentPath = window.location.pathname;

// Iterate over the versions object
for (const [versionName, versionUrl] of Object.entries(versions)) {
const option = document.createElement("option");
option.value = versionUrl + '/';
option.textContent = versionName;

// Check if the current URL matches this option's value
if (currentPath.includes(option.value)) {
option.selected = true; // Set this option as selected
}

versionSelector.appendChild(option);
}

// Event listener to handle version change
versionSelector.addEventListener("change", function() {
const selectedVersion = versionSelector.value;
// Redirect to the selected version URL
window.location.href = '/zksync-era/core' + selectedVersion;
});

return versionSelector;
}

// Fetch versions from JSON file
fetch(baseUrl + '/versions.json')
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok ' + response.statusText);
}
return response.json();
})
.then(data => {
const versionSelector = createVersionSelector(data);
const nav = document.querySelector(".right-buttons");

if (nav) {
const versionBox = document.createElement("div");
versionBox.id = "version-box";
versionBox.appendChild(versionSelector);
nav.appendChild(versionBox); // Append to the .right-buttons container
} else {
console.error(".right-buttons element not found.");
}
})
.catch(error => {
console.error('There has been a problem with your fetch operation:', error);
});
});
19 changes: 19 additions & 0 deletions docs/src/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Introduction

Welcome to the documentation! This guide provides comprehensive insights into the architecture, setup, usage, and advanced features of ZKsync.

## Documentation Structure

- **Guides**: The Guides section is designed to help users at every level, from setup and development to advanced configuration and debugging techniques. It covers essential topics, including Docker setup, repository management, and architecture.

- **Specs**: This section dives into the technical specifications of our system. Here, you’ll find detailed documentation on data availability, L1 and L2 communication, smart contract interactions, Zero-Knowledge proofs, and more. Each topic includes an in-depth explanation to support advanced users and developers.

- **Announcements**: This section highlights important updates, announcements, and committee details, providing essential information to keep users informed on the latest changes.

## Getting Started

Feel free to explore each section according to your needs. This documentation is designed to be modular, so you can jump to specific topics or follow through step-by-step.

---

Thank you for using our documentation!
82 changes: 82 additions & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Summary

[Introduction](README.md)

# Guides

- [Basic](guides/README.md)
- [Architecture](guides/architecture.md)
- [Build Docker](guides/build-docker.md)
- [Development](guides/development.md)
- [Launch](guides/launch.md)
- [Repositories](guides/repositories.md)
- [Setup Dev](guides/setup-dev.md)

- [Advanced](guides/advanced/README.md)
- [Local initialization](guides/advanced/01_initialization.md)
- [Deposits](guides/advanced/02_deposits.md)
- [Withdrawals](guides/advanced/03_withdrawals.md)
- [Contracts](guides/advanced/04_contracts.md)
- [Calls](guides/advanced/05_how_call_works.md)
- [Transactions](guides/advanced/06_how_transaction_works.md)
- [Fee Model](guides/advanced/07_fee_model.md)
- [L2 Messaging](guides/advanced/08_how_l2_messaging_works.md)
- [Pubdata](guides/advanced/09_pubdata.md)
- [Pubdata with Blobs](guides/advanced/10_pubdata_with_blobs.md)
- [Bytecode compression](guides/advanced/11_compression.md)
- [EraVM intro](guides/advanced/12_alternative_vm_intro.md)
- [ZK Intuition](guides/advanced/13_zk_intuition.md)
- [ZK Deeper Dive](guides/advanced/14_zk_deeper_overview.md)
- [Prover Keys](guides/advanced/15_prover_keys.md)
- [Advanced Debugging](guides/advanced/90_advanced_debugging.md)
- [Docker and CI](guides/advanced/91_docker_and_ci.md)

# External Node

- [External node](guides/external-node/01_intro.md)
- [Quick Start](guides/external-node/00_quick_start.md)
- [Configuration](guides/external-node/02_configuration.md)
- [Running](guides/external-node/03_running.md)
- [Observability](guides/external-node/04_observability.md)
- [Troubleshooting](guides/external-node/05_troubleshooting.md)
- [Components](guides/external-node/06_components.md)
- [Snapshots Recovery](guides/external-node/07_snapshots_recovery.md)
- [Pruning](guides/external-node/08_pruning.md)
- [Treeless Mode](guides/external-node/09_treeless_mode.md)

# Specs

- [Introduction](specs/introduction.md)
- [Overview](specs/overview.md)
- [Blocks and Batches](specs/blocks_batches.md)
- [L1 Smart Contracts](specs/l1_smart_contracts.md)
- [Data Availability](specs/data_availability/overview.md)
- [Pubdata](specs/data_availability/pubdata.md)
- [Compression](specs/data_availability/compression.md)
- [Reconstruction](specs/data_availability/reconstruction.md)
- [Validium ZK Porter](specs/data_availability/validium_zk_porter.md)
- [L1 L2 Communication](specs/l1_l2_communication/overview_deposits_withdrawals.md)
- [L1 to L2](specs/l1_l2_communication/l1_to_l2.md)
- [L2 to L1](specs/l1_l2_communication/l2_to_l1.md)
- [Prover](specs/prover/overview.md)
- [Getting Started](specs/prover/getting_started.md)
- [ZK Terminology](specs/prover/zk_terminology.md)
- [Function Check if Satisfied](specs/prover/boojum_function_check_if_satisfied.md)
- [Gadgets](specs/prover/boojum_gadgets.md)
- [Circuit Testing](specs/prover/circuit_testing.md)
- [Circuits Overview](specs/prover/circuits/overview.md)
- [ZK Chains](specs/zk_chains/overview.md)
- [Gateway](specs/zk_chains/gateway.md)
- [Interop](specs/zk_chains/interop.md)
- [Shared Bridge](specs/zk_chains/shared_bridge.md)
- [ZK EVM](specs/zk_evm/vm_overview.md)
- [Account Abstraction](specs/zk_evm/account_abstraction.md)
- [Bootloader](specs/zk_evm/bootloader.md)
- [Fee Model](specs/zk_evm/fee_model.md)
- [Precompiles](specs/zk_evm/precompiles.md)
- [System Contracts](specs/zk_evm/system_contracts.md)

# Announcements

- [Announcements](announcements/README.md)
- [Attester Committee](announcements/attester_commitee.md)
File renamed without changes.
File renamed without changes.
12 changes: 12 additions & 0 deletions docs/src/guides/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# ZKsync basic guides

This section contains basic guides that aim to explain the ZKsync ecosystem in an easy to grasp way.

## Table of Contents

- [Architecture](./architecture.md)
- [Build Docker](./build-docker.md)
- [Development](./development.md)
- [Launch](./launch.md)
- [Repositories](./repositories.md)
- [Setup Dev](./setup-dev.md)
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ way.
- [Prover keys](./15_prover_keys.md)

Additionally, there are a few articles that cover specific topics that may be useful for developers actively working on
`zksync-era` repo.
`zksync-era` repo:

- [Advanced debugging](./90_advanced_debugging.md)
- [Docker and CI](./91_docker_and_ci.md)
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit 9785095

Please sign in to comment.