Docusaurus website

.github/workflows/docs.yaml

@@ -0,0 +1,182 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - develop
+    tags:
+      - 'v*'
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yaml'
+  pull_request:
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yaml'
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: '20'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Test documentation build
+  test-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Setup build dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y protobuf-compiler
+
+      - name: Install dependencies
+        run: make docs-install
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+          toolchain: nightly
+
+      - name: Test documentation build
+        run: make docs-build
+
+      - name: Upload build artifacts for testing
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build-test
+          path: website/build
+          retention-days: 1
+
+
+  # Deploy to GitHub Pages (only on develop branch)
+  deploy:
+    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
+    needs: [test-docs]
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for versioning
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Setup build dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y protobuf-compiler
+
+      - name: Install documentation dependencies
+        run: make docs-install
+
+      - name: Build documentation
+        run: |
+          cd website
+          # Set base URL for GitHub Pages
+          echo "Building documentation for GitHub Pages..."
+          npm run build
+        env:
+          NODE_ENV: production
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  # Create versioned documentation on tag creation
+  version-docs:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test-docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        run: make docs-install
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Creating version $VERSION"
+
+      - name: Create versioned documentation
+        run: |
+          cd website
+          # Create a new version of the documentation
+          npm run docusaurus docs:version ${{ steps.version.outputs.version }}
+
+      - name: Setup build dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y protobuf-compiler
+
+      - name: Build versioned documentation
+        run: |
+          cd website
+          npm run build
+        env:
+          NODE_ENV: production
+
+      - name: Create versioned documentation archive
+        run: |
+          cd website/build
+          tar -czf "../../openmina-docs-${{ steps.version.outputs.version }}.tar.gz" .
+          cd ../..
+          zip -r "openmina-docs-${{ steps.version.outputs.version }}.zip" website/build
+
+      - name: Upload versioned documentation as release asset
+        uses: actions/upload-artifact@v4
+        with:
+          name: versioned-docs-${{ steps.version.outputs.version }}
+          path: |
+            openmina-docs-${{ steps.version.outputs.version }}.tar.gz
+            openmina-docs-${{ steps.version.outputs.version }}.zip

.github/workflows/lint.yml

@@ -18,15 +18,22 @@ jobs:
       - name: Setup build dependencies
         run: |
           sudo apt update || true
-          sudo apt install -y protobuf-compiler || true
+          sudo apt install -y protobuf-compiler sqlite3 || true
+      - name: Setup SQLite database for SQLx
+        run: |
+          sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql
       - uses: dtolnay/rust-toolchain@stable
         with:
           toolchain: ${{ matrix.toolchain }}
           components: clippy, rustfmt
       - name: Run make check
         run: make check
+        env:
+          DATABASE_URL: "sqlite:///tmp/heartbeats.db"
       - name: Run make lint
         run: make lint
+        env:
+          DATABASE_URL: "sqlite:///tmp/heartbeats.db"
 
   lint-tx-fuzzing:
     name: Lint transaction Fuzzing - ${{ matrix.os }} - Rust ${{ matrix.toolchain }}

.github/workflows/test-docs-scripts.yml

@@ -0,0 +1,100 @@
+name: Test Documentation Scripts
+
+# This workflow tests the documentation setup scripts to ensure they work correctly.
+# It runs nightly and on-demand to avoid slowing down regular development workflow,
+# since documentation builds can take a long time to complete.
+on:
+  pull_request:
+    types: [labeled]
+    # Only runs when 'test-doc-scripts' label is added to a PR
+  schedule:
+    # Run nightly to catch environment drift and ensure scripts stay functional
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+    # Allow manual triggering for testing
+
+jobs:
+  test-system-setup:
+    name: Test System Setup Scripts (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    # Only run if the event is scheduled, manual, or PR has test-doc-scripts label
+    # This prevents long-running tests from blocking regular development workflow
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test system dependencies installation
+        run: |
+          ./website/docs/developers/scripts/setup/install-system-deps.sh
+
+      - name: Test Node.js installation
+        run: |
+          ./website/docs/developers/scripts/setup/install-nodejs.sh
+
+      - name: Test Rust installation
+        run: |
+          ./website/docs/developers/scripts/setup/install-rust.sh
+
+      - name: Test WASM tools installation
+        run: |
+          # Source cargo environment first
+          source ~/.cargo/env
+          ./website/docs/developers/scripts/setup/install-wasm-tools.sh
+
+      - name: Test specialised builds
+        run: |
+          # Source cargo environment first
+          source ~/.cargo/env
+          ./website/docs/developers/scripts/setup/build-specialized.sh
+
+      - name: Test format and lint
+        run: |
+          # Source cargo environment first
+          source ~/.cargo/env
+          ./website/docs/developers/scripts/setup/format-and-lint.sh
+
+      - name: Test run tests
+        run: |
+          # Source cargo environment first
+          source ~/.cargo/env
+          ./website/docs/developers/scripts/setup/run-tests.sh
+
+      - name: Verify installations
+        run: |
+          echo "Verifying installed tools..."
+          source ~/.cargo/env
+          rustc --version
+          cargo --version
+          node --version
+          npm --version
+          protoc --version
+          sqlite3 --version
+          wasm-pack --version
+
+  test-docker-setup:
+    name: Test Docker Setup Script (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    # Only run if the event is scheduled, manual, or PR has test-doc-scripts label
+    # This prevents long-running tests from blocking regular development workflow
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Test Docker installation
+        run: |
+          ./website/docs/developers/scripts/setup/install-docker.sh
+
+      - name: Verify Docker installation
+        run: |
+          sudo docker --version
+          sudo docker run hello-world

.github/workflows/whitespace-check.yaml

@@ -0,0 +1,17 @@
+name: Trailing Whitespace Check
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  check-whitespace:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check for trailing whitespaces
+        run: make check-trailing-whitespace

.gitignore

@@ -10,4 +10,7 @@ pkg/
 
 # Outputs of build-tests-webrtc
 cargo-build-test.json
-tests.tsv
+tests.tsv
+
+# Generated API docs should not be committed
+website/static/api-docs/

CHANGELOG.md

@@ -13,6 +13,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1236](https://github.com/o1-labs/openmina/pull/1236), fix
   [#1158](https://github.com/o1-labs/openmina/issues/1158))
 
+### Added
+
+- **Documentation**: Complete Docusaurus-based documentation website with
+  comprehensive guides for node runners, developers, and researchers
+  ([#1234](https://github.com/o1-labs/openmina/pull/1234)). It migrates all the
+  documentation from `docs` to `website/docs`. It includes SEO metadata and
+  social media integration.
+- **Documentation**: Developer getting-started guide with automated setup
+  scripts for system dependencies, Rust toolchain, Node.js, Docker, and WASM
+  tools. This is run nightly and on-demand via PR labels to avoid blocking
+  development workflow. ([#1234](https://github.com/o1-labs/openmina/pull/1234)).
+- **Development Tools**: Enhanced formatting infrastructure with MDX file
+  support and trailing whitespace management
+  ([#1234](https://github.com/o1-labs/openmina/pull/1234))
+
+### Changed
+
+- **Build System**: Enhanced Makefile with documentation-related targets and comprehensive formatting commands ([#1234](https://github.com/o1-labs/openmina/pull/1234))
+
+### Fixed
+
+- **Documentation**: Resolved broken links and bare URL warnings in Rust
+  documentation ([#1234](https://github.com/o1-labs/openmina/pull/1234))
+- **Build System**: Fixed SQLx compilation errors in lint workflow
+  ([#1234](https://github.com/o1-labs/openmina/pull/1234))
+- **Formatting**: Standardized markdown and MDX files to 80-character line
+  wrapping ([#1234](https://github.com/o1-labs/openmina/pull/1234))
+
 ### Dependencies
 
 - bump proc-macro2 from 1.0.93 to 1.0.95