1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
# Copyright © 2025-2026 Wenze Wei. All Rights Reserved.
#
# This file is part of Ri.
# The Ri project belongs to the Dunimd Team.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# You may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
################################################################################
# Ri Documentation Deployment Pipeline
################################################################################
#
# PURPOSE:
# This workflow automates the build and deployment of Ri project documentation
# to GitHub Pages. It generates and publishes comprehensive API documentation
# for both the Rust library and Python bindings.
#
# DOCUMENTATION COMPONENTS GENERATED:
# 1. Rust API Documentation (cargo doc)
# - Automatically generated from Rust source code doc comments
# - Uses --no-deps to document only the local crate, not dependencies
# - Uses --features full to include all feature-gated code
#
# 2. Python API Documentation (pdoc)
# - Generated from Python docstrings using pdoc tool
# - Targets the ri Python package
# - Provides Python-specific API reference
#
# 3. Redirect Index
# - Auto-generated HTML redirect from root to documentation
# - Ensures users land on the correct documentation page
#
# OUTPUT LOCATION: target/doc/
# PUBLISHING TARGET: GitHub Pages (https://<username>.github.io/<repo>/ri/)
#
# TRIGGER CONDITIONS:
# - push to master or main branches: Automatic deployment
# - workflow_dispatch: Manual trigger for on-demand updates
#
# PERMISSIONS REQUIRED:
# - contents: read - Required to checkout repository
# - pages: write - Required to deploy to GitHub Pages
# - id-token: write - Required for OpenID Connect authentication
#
# CONCURRENCY SETTINGS:
# - Group: "pages" ensures only one deployment runs at a time
# - cancel-in-progress: false allows ongoing deployments to complete
#
# DEPENDENCIES:
# - Rust toolchain (stable)
# - Python 3.11 with maturin and pdoc
# - System packages: libcurl4-openssl-dev, libsasl2-dev, libssl-dev, protobuf-compiler
#
# DEPLOYMENT FLOW:
# 1. Checkout source code
# 2. Install Rust toolchain and Python environment
# 3. Install system dependencies (OpenSSL, SASL, protobuf)
# 4. Cache Cargo dependencies for faster builds
# 5. Build Rust documentation
# 6. Build Python wheel with maturin
# 7. Install Python package locally
# 8. Generate Python documentation with pdoc
# 9. Create redirect index.html
# 10. Upload Pages artifact
# 11. Deploy to GitHub Pages
################################################################################
name: Deploy Docs
on:
push:
branches:
- master
- main
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
################################################################################
# Job: Build Documentation
################################################################################
# This job builds all documentation components and prepares them for deployment.
# It runs on ubuntu-latest runner and produces a Pages artifact.
#
# Build Steps Overview:
# 1. Checkout repository at the triggering commit
# 2. Set up Rust stable toolchain
# 3. Set up Python 3.11
# 4. Install system dependencies required for building dependencies
# 5. Cache Cargo registry and build artifacts
# 6. Install maturin and pdoc Python tools
# 7. Generate Rust API documentation
# 8. Build Python wheel package
# 9. Install the Python package locally
# 10. Generate Python API documentation
# 11. Create redirect index.html
# 12. Upload artifact for GitHub Pages deployment
################################################################################
build-docs:
runs-on: ubuntu-latest
steps:
# Step 1: Checkout Repository
# Clones the repository to access source code for documentation generation.
# Uses actions/checkout@v4 for latest features and security updates.
- uses: actions/checkout@v4
# Step 2: Set Up Rust Toolchain
# Installs the stable Rust toolchain which is required to compile the
# Rust library and generate API documentation.
# Uses dtolnay/rust-toolchain for reliable Rust installation.
- uses: dtolnay/rust-toolchain@stable
# Step 3: Set Up Python Environment
# Configures Python 3.11 for building the Python wheel and generating
# Python documentation. Python is needed to run maturin and pdoc tools.
- uses: actions/setup-python@v5
with:
python-version: '3.11'
# Step 4: Install System Dependencies
# These system packages are required for building native dependencies
# that the Rust crate links against:
# - libcurl4-openssl-dev: HTTP client library (for rdkafka, etcd-client)
# - libsasl2-dev: SASL authentication library (for Kafka authentication)
# - libssl-dev: SSL/TLS library (for secure communications)
# - protobuf-compiler: Protocol Buffers compiler (for etcd-client)
# - liboqs-dev: Post-quantum cryptography library (for protocol feature)
- name: Install system dependencies
run: |
sudo apt-get update
echo 'deb [trusted=yes] https://pkgs.kquirk.com/apt all main' | sudo tee /etc/apt/sources.list.d/oqs.list > /dev/null || true
sudo apt-get update || true
if ! sudo apt-get install -y liboqs-dev 2>/dev/null; then
echo "Building liboqs from source..."
sudo apt-get install -y libcurl4-openssl-dev libsasl2-dev libssl-dev protobuf-compiler build-essential pkg-config cmake git ninja-build
cd /tmp && rm -rf liboqs && git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git
cd liboqs && mkdir -p build && cd build && \
cmake -GNinja -DCMAKE_INSTALL_PREFIX=/usr .. && \
ninja && sudo ninja install && sudo ldconfig
fi
sudo apt-get install -y libcurl4-openssl-dev libsasl2-dev libssl-dev protobuf-compiler
# Step 5: Cache Cargo Dependencies
# Caches Cargo registry index, git checkouts, and target directory
# to significantly speed up subsequent builds by avoiding re-downloading
# and re-compiling dependencies.
- name: Cache Cargo dependencies
uses: actions/cache@v4
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-docs-${{ hashFiles('**/Cargo.lock') }}
# Step 6: Install Python Documentation Tools
# - maturin: Build tool for Python/Rust projects, generates wheel and bindings
# - pdoc: Documentation generator for Python projects
# pip install is used as these are Python packages.
- name: Install Python tools
run: pip install maturin pdoc
# Step 7: Build Rust API Documentation
# Generates HTML documentation from Rust source code doc comments.
# --no-deps: Only documents the local crate, not dependencies
# --features full: Enables all features to document complete API
# Output: target/doc/ directory with generated HTML
- name: Build Rust documentation
run: OPENSSL_NO_VENDOR=1 cargo doc --no-deps --features full
# Step 8: Build Python Wheel Package
# Uses maturin to build a Python wheel (.whl) containing the Rust library
# compiled as a Python extension module.
# --release: Uses release optimization profile
# --features pyo3: Enables PyO3 Python bindings
# -o dist: Outputs wheel to dist/ directory
- name: Build Python wheel
run: OPENSSL_NO_VENDOR=1 maturin build --release --features pyo3 -o dist
# Step 9: Install Python Package Locally
# Installs the built wheel into the Python environment so that pdoc
# can extract docstrings from the installed package.
- name: Install Python package
run: pip install dist/*.whl
# Step 10: Build Python API Documentation
# Uses pdoc to generate HTML documentation from Python docstrings.
# Targets the 'ri' module (the Python package name).
# Output: target/doc/python/ directory with generated HTML
- name: Build Python documentation
run: pdoc -o target/doc/python ri
# Step 11: Create Redirect Index
# Creates an index.html that automatically redirects users to the
# main documentation page. This provides a cleaner URL structure
# where accessing the root redirects to /ri/ documentation.
- name: Add redirect index
run: |
cat > target/doc/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0;url=ri/">
</head>
<body>
<a href="ri/">Go to Ri Documentation</a>
</body>
</html>
EOF
# Step 12: Upload Pages Artifact
# Packages the documentation directory as a Pages artifact for deployment.
# Uses actions/upload-pages-artifact@v3 for GitHub Pages deployment.
# The artifact contains all HTML documentation ready for web hosting.
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: target/doc
################################################################################
# Job: Deploy to GitHub Pages
################################################################################
# This job takes the documentation artifact and deploys it to GitHub Pages.
# It depends on build-docs completing successfully and uses OIDC for
# secure authentication with GitHub Pages.
#
# Deployment Requirements:
# - GitHub Pages must be enabled for the repository
# - environment 'github-pages' must be configured
# - OIDC token for secure deployment authentication
#
# Output: Published documentation at GitHub Pages URL
################################################################################
deploy-docs:
needs: build-docs
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
# Step 1: Deploy to GitHub Pages
# Uses actions/deploy-pages@v4 to deploy the uploaded artifact.
# The deployment URL is stored in outputs.page_url for reference.
# GitHub Pages serves the documentation at:
# https://<username>.github.io/<repository>/ri/
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4