Skip to content

Commit f5200db

Browse files
dannywillemsdannywillems
authored
Merge pull request #1234 from o1-labs/dw/docs-docusaurus
Docusaurus website
2 parents d97a74a + 9f02aa0 commit f5200db

File tree

138 files changed

+20390
-1161
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

138 files changed

+20390
-1161
lines changed

‎.github/workflows/docs.yaml

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- develop
7+
tags:
8+
- 'v*'
9+
paths:
10+
- 'website/**'
11+
- 'docs/**'
12+
- '.github/workflows/docs.yaml'
13+
pull_request:
14+
paths:
15+
- 'website/**'
16+
- 'docs/**'
17+
- '.github/workflows/docs.yaml'
18+
workflow_dispatch:
19+
20+
env:
21+
NODE_VERSION: '20'
22+
23+
concurrency:
24+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
25+
cancel-in-progress: true
26+
27+
jobs:
28+
# Test documentation build
29+
test-docs:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
35+
- name: Setup Node.js
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: ${{ env.NODE_VERSION }}
39+
cache: 'npm'
40+
cache-dependency-path: website/package-lock.json
41+
42+
- name: Setup build dependencies
43+
run: |
44+
sudo apt update
45+
sudo apt install -y protobuf-compiler
46+
47+
- name: Install dependencies
48+
run: make docs-install
49+
50+
- name: Setup Rust
51+
uses: dtolnay/rust-toolchain@stable
52+
with:
53+
components: rustfmt
54+
toolchain: nightly
55+
56+
- name: Test documentation build
57+
run: make docs-build
58+
59+
- name: Upload build artifacts for testing
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: docs-build-test
63+
path: website/build
64+
retention-days: 1
65+
66+
67+
# Deploy to GitHub Pages (only on develop branch)
68+
deploy:
69+
if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
70+
needs: [test-docs]
71+
runs-on: ubuntu-latest
72+
environment:
73+
name: github-pages
74+
url: ${{ steps.deployment.outputs.page_url }}
75+
76+
permissions:
77+
contents: read
78+
pages: write
79+
id-token: write
80+
81+
steps:
82+
- name: Checkout repository
83+
uses: actions/checkout@v4
84+
with:
85+
fetch-depth: 0 # Full history for versioning
86+
87+
- name: Setup Node.js
88+
uses: actions/setup-node@v4
89+
with:
90+
node-version: ${{ env.NODE_VERSION }}
91+
cache: 'npm'
92+
cache-dependency-path: website/package-lock.json
93+
94+
- name: Setup Pages
95+
uses: actions/configure-pages@v4
96+
97+
- name: Setup build dependencies
98+
run: |
99+
sudo apt update
100+
sudo apt install -y protobuf-compiler
101+
102+
- name: Install documentation dependencies
103+
run: make docs-install
104+
105+
- name: Build documentation
106+
run: |
107+
cd website
108+
# Set base URL for GitHub Pages
109+
echo "Building documentation for GitHub Pages..."
110+
npm run build
111+
env:
112+
NODE_ENV: production
113+
114+
- name: Upload to GitHub Pages
115+
uses: actions/upload-pages-artifact@v3
116+
with:
117+
path: website/build
118+
119+
- name: Deploy to GitHub Pages
120+
id: deployment
121+
uses: actions/deploy-pages@v4
122+
123+
# Create versioned documentation on tag creation
124+
version-docs:
125+
if: startsWith(github.ref, 'refs/tags/v')
126+
needs: [test-docs]
127+
runs-on: ubuntu-latest
128+
steps:
129+
- name: Checkout repository
130+
uses: actions/checkout@v4
131+
with:
132+
fetch-depth: 0
133+
134+
- name: Setup Node.js
135+
uses: actions/setup-node@v4
136+
with:
137+
node-version: ${{ env.NODE_VERSION }}
138+
cache: 'npm'
139+
cache-dependency-path: website/package-lock.json
140+
141+
- name: Install dependencies
142+
run: make docs-install
143+
144+
- name: Extract version from tag
145+
id: version
146+
run: |
147+
VERSION=${GITHUB_REF#refs/tags/v}
148+
echo "version=$VERSION" >> $GITHUB_OUTPUT
149+
echo "Creating version $VERSION"
150+
151+
- name: Create versioned documentation
152+
run: |
153+
cd website
154+
# Create a new version of the documentation
155+
npm run docusaurus docs:version ${{ steps.version.outputs.version }}
156+
157+
- name: Setup build dependencies
158+
run: |
159+
sudo apt update
160+
sudo apt install -y protobuf-compiler
161+
162+
- name: Build versioned documentation
163+
run: |
164+
cd website
165+
npm run build
166+
env:
167+
NODE_ENV: production
168+
169+
- name: Create versioned documentation archive
170+
run: |
171+
cd website/build
172+
tar -czf "../../openmina-docs-${{ steps.version.outputs.version }}.tar.gz" .
173+
cd ../..
174+
zip -r "openmina-docs-${{ steps.version.outputs.version }}.zip" website/build
175+
176+
- name: Upload versioned documentation as release asset
177+
uses: actions/upload-artifact@v4
178+
with:
179+
name: versioned-docs-${{ steps.version.outputs.version }}
180+
path: |
181+
openmina-docs-${{ steps.version.outputs.version }}.tar.gz
182+
openmina-docs-${{ steps.version.outputs.version }}.zip

‎.github/workflows/lint.yml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,22 @@ jobs:
1818
- name: Setup build dependencies
1919
run: |
2020
sudo apt update || true
21-
sudo apt install -y protobuf-compiler || true
21+
sudo apt install -y protobuf-compiler sqlite3 || true
22+
- name: Setup SQLite database for SQLx
23+
run: |
24+
sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql
2225
- uses: dtolnay/rust-toolchain@stable
2326
with:
2427
toolchain: ${{ matrix.toolchain }}
2528
components: clippy, rustfmt
2629
- name: Run make check
2730
run: make check
31+
env:
32+
DATABASE_URL: "sqlite:///tmp/heartbeats.db"
2833
- name: Run make lint
2934
run: make lint
35+
env:
36+
DATABASE_URL: "sqlite:///tmp/heartbeats.db"
3037

3138
lint-tx-fuzzing:
3239
name: Lint transaction Fuzzing - ${{ matrix.os }} - Rust ${{ matrix.toolchain }}

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
name: Test Documentation Scripts
2+
3+
# This workflow tests the documentation setup scripts to ensure they work correctly.
4+
# It runs nightly and on-demand to avoid slowing down regular development workflow,
5+
# since documentation builds can take a long time to complete.
6+
on:
7+
pull_request:
8+
types: [labeled]
9+
# Only runs when 'test-doc-scripts' label is added to a PR
10+
schedule:
11+
# Run nightly to catch environment drift and ensure scripts stay functional
12+
- cron: '0 2 * * *'
13+
workflow_dispatch:
14+
# Allow manual triggering for testing
15+
16+
jobs:
17+
test-system-setup:
18+
name: Test System Setup Scripts (${{ matrix.os }})
19+
runs-on: ${{ matrix.os }}
20+
# Only run if the event is scheduled, manual, or PR has test-doc-scripts label
21+
# This prevents long-running tests from blocking regular development workflow
22+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
23+
strategy:
24+
matrix:
25+
os: [ubuntu-22.04, ubuntu-24.04]
26+
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
31+
- name: Test system dependencies installation
32+
run: |
33+
./website/docs/developers/scripts/setup/install-system-deps.sh
34+
35+
- name: Test Node.js installation
36+
run: |
37+
./website/docs/developers/scripts/setup/install-nodejs.sh
38+
39+
- name: Test Rust installation
40+
run: |
41+
./website/docs/developers/scripts/setup/install-rust.sh
42+
43+
- name: Test WASM tools installation
44+
run: |
45+
# Source cargo environment first
46+
source ~/.cargo/env
47+
./website/docs/developers/scripts/setup/install-wasm-tools.sh
48+
49+
- name: Test specialised builds
50+
run: |
51+
# Source cargo environment first
52+
source ~/.cargo/env
53+
./website/docs/developers/scripts/setup/build-specialized.sh
54+
55+
- name: Test format and lint
56+
run: |
57+
# Source cargo environment first
58+
source ~/.cargo/env
59+
./website/docs/developers/scripts/setup/format-and-lint.sh
60+
61+
- name: Test run tests
62+
run: |
63+
# Source cargo environment first
64+
source ~/.cargo/env
65+
./website/docs/developers/scripts/setup/run-tests.sh
66+
67+
- name: Verify installations
68+
run: |
69+
echo "Verifying installed tools..."
70+
source ~/.cargo/env
71+
rustc --version
72+
cargo --version
73+
node --version
74+
npm --version
75+
protoc --version
76+
sqlite3 --version
77+
wasm-pack --version
78+
79+
test-docker-setup:
80+
name: Test Docker Setup Script (${{ matrix.os }})
81+
runs-on: ${{ matrix.os }}
82+
# Only run if the event is scheduled, manual, or PR has test-doc-scripts label
83+
# This prevents long-running tests from blocking regular development workflow
84+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
85+
strategy:
86+
matrix:
87+
os: [ubuntu-22.04, ubuntu-24.04]
88+
89+
steps:
90+
- name: Checkout repository
91+
uses: actions/checkout@v4
92+
93+
- name: Test Docker installation
94+
run: |
95+
./website/docs/developers/scripts/setup/install-docker.sh
96+
97+
- name: Verify Docker installation
98+
run: |
99+
sudo docker --version
100+
sudo docker run hello-world

‎.github/workflows/whitespace-check.yaml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Trailing Whitespace Check
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
check-whitespace:
11+
runs-on: ubuntu-22.04
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v4
15+
16+
- name: Check for trailing whitespaces
17+
run: make check-trailing-whitespace

‎.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,7 @@ pkg/
1010

1111
# Outputs of build-tests-webrtc
1212
cargo-build-test.json
13-
tests.tsv
13+
tests.tsv
14+
15+
# Generated API docs should not be committed
16+
website/static/api-docs/

‎CHANGELOG.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313
([#1236](https://github.com/o1-labs/openmina/pull/1236), fix
1414
[#1158](https://github.com/o1-labs/openmina/issues/1158))
1515

16+
### Added
17+
18+
- **Documentation**: Complete Docusaurus-based documentation website with
19+
comprehensive guides for node runners, developers, and researchers
20+
([#1234](https://github.com/o1-labs/openmina/pull/1234)). It migrates all the
21+
documentation from `docs` to `website/docs`. It includes SEO metadata and
22+
social media integration.
23+
- **Documentation**: Developer getting-started guide with automated setup
24+
scripts for system dependencies, Rust toolchain, Node.js, Docker, and WASM
25+
tools. This is run nightly and on-demand via PR labels to avoid blocking
26+
development workflow. ([#1234](https://github.com/o1-labs/openmina/pull/1234)).
27+
- **Development Tools**: Enhanced formatting infrastructure with MDX file
28+
support and trailing whitespace management
29+
([#1234](https://github.com/o1-labs/openmina/pull/1234))
30+
31+
### Changed
32+
33+
- **Build System**: Enhanced Makefile with documentation-related targets and comprehensive formatting commands ([#1234](https://github.com/o1-labs/openmina/pull/1234))
34+
35+
### Fixed
36+
37+
- **Documentation**: Resolved broken links and bare URL warnings in Rust
38+
documentation ([#1234](https://github.com/o1-labs/openmina/pull/1234))
39+
- **Build System**: Fixed SQLx compilation errors in lint workflow
40+
([#1234](https://github.com/o1-labs/openmina/pull/1234))
41+
- **Formatting**: Standardized markdown and MDX files to 80-character line
42+
wrapping ([#1234](https://github.com/o1-labs/openmina/pull/1234))
43+
1644
### Dependencies
1745

1846
- bump proc-macro2 from 1.0.93 to 1.0.95

0 commit comments

Comments
 (0)