From 66fc85c4f465ed616ddc9b99b01a1b8cdb5aa72d Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Thu, 2 Oct 2025 16:23:07 +0200 Subject: [PATCH 1/2] Website: add documentation guidelines + code ref in doc --- .github/scripts/verify-code-references.sh | 150 ++++++++++++++++++ .github/workflows/docs.yaml | 3 + .../developers/documentation-guidelines.md | 124 +++++++++++++++ website/docusaurus.config.ts | 2 + website/package-lock.json | 10 ++ website/package.json | 1 + website/sidebars.ts | 7 + 7 files changed, 297 insertions(+) create mode 100755 .github/scripts/verify-code-references.sh create mode 100644 website/docs/developers/documentation-guidelines.md diff --git a/.github/scripts/verify-code-references.sh b/.github/scripts/verify-code-references.sh new file mode 100755 index 0000000000..12fb665f73 --- /dev/null +++ b/.github/scripts/verify-code-references.sh @@ -0,0 +1,150 @@ +#!/usr/bin/env bash +# Verify that code references in documentation match actual source code +# This script extracts CODE_REFERENCE comments from markdown files and validates +# that the referenced code still exists at the specified line numbers + +set -euo pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +DOCS_DIR="${REPO_ROOT}/website/docs" +EXIT_CODE=0 +TOTAL_REFS=0 +VALID_REFS=0 +INVALID_REFS=0 + +echo "Verifying code references in documentation..." +echo "Repository root: ${REPO_ROOT}" +echo "" + +# Find all markdown files with CODE_REFERENCE comments +while IFS= read -r doc_file; do + # Extract CODE_REFERENCE comments from this file + while IFS= read -r line_num; do + # Get the actual line content + comment_line=$(sed -n "${line_num}p" "$doc_file") + + # Extract file path and line range from comment + # Format: + if [[ $comment_line =~ CODE_REFERENCE:\ *([^#]+)#L([0-9]+)-L([0-9]+) ]]; then + file_path="${BASH_REMATCH[1]}" + start_line="${BASH_REMATCH[2]}" + end_line="${BASH_REMATCH[3]}" + + # Trim whitespace from file_path + file_path=$(echo "$file_path" | xargs) + + TOTAL_REFS=$((TOTAL_REFS + 1)) + + # Check if the source file exists + source_file="${REPO_ROOT}/${file_path}" + if [[ ! -f "$source_file" ]]; then + echo -e "${RED}✗${NC} Invalid reference in ${doc_file}:${line_num}" + echo " File not found: ${file_path}" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + continue + fi + + # Check if the line range is valid + total_lines=$(wc -l < "$source_file") + if [[ $end_line -gt $total_lines ]]; then + echo -e "${RED}✗${NC} Invalid reference in ${doc_file}:${line_num}" + echo " Line range L${start_line}-L${end_line} exceeds file length (${total_lines} lines)" + echo " File: ${file_path}" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + continue + fi + + # Extract the actual code from source file + actual_code=$(sed -n "${start_line},${end_line}p" "$source_file") + + # Find the corresponding code block in the markdown (should be right after the comment) + # Look for ```rust reference block within next 5 lines + code_block_start=$((line_num + 1)) + code_block_end=$((line_num + 10)) + + # Extract GitHub URL from the reference block + github_url=$(sed -n "${code_block_start},${code_block_end}p" "$doc_file" | grep "github.com" | head -1) + + if [[ -n "${github_url}" ]]; then + # Verify the GitHub URL contains correct line range + line_range_pattern="#L${start_line}-L${end_line}" + if [[ "${github_url}" =~ ${line_range_pattern} ]]; then + # Extract GitHub raw URL from the reference + # Convert: https://github.com/o1-labs/mina-rust/blob/develop/path/to/file.rs#L10-L20 + # To: https://raw.githubusercontent.com/o1-labs/mina-rust/develop/path/to/file.rs + if [[ "${github_url}" =~ github\.com/([^/]+)/([^/]+)/blob/([^/]+)/([^#]+) ]]; then + org="${BASH_REMATCH[1]}" + repo="${BASH_REMATCH[2]}" + branch="${BASH_REMATCH[3]}" + gh_file_path="${BASH_REMATCH[4]}" + + raw_url="https://raw.githubusercontent.com/${org}/${repo}/${branch}/${gh_file_path}" + + # Fetch the code from GitHub + github_code=$(curl -s "${raw_url}" | sed -n "${start_line},${end_line}p") + + # Compare local code with GitHub code + if [[ "${actual_code}" == "${github_code}" ]]; then + echo -e "${GREEN}✓${NC} Valid reference in ${doc_file}:${line_num}" + echo " ${file_path}#L${start_line}-L${end_line}" + echo " Local code matches GitHub (${branch})" + VALID_REFS=$((VALID_REFS + 1)) + else + echo -e "${RED}✗${NC} Code mismatch in ${doc_file}:${line_num}" + echo " ${file_path}#L${start_line}-L${end_line}" + echo " Local code differs from GitHub (${branch})" + echo " This may indicate uncommitted changes or branch divergence" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + fi + else + echo -e "${YELLOW}⚠${NC} Could not parse GitHub URL in ${doc_file}:${line_num}" + echo " URL: ${github_url}" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + fi + else + echo -e "${YELLOW}⚠${NC} Mismatched line range in ${doc_file}:${line_num}" + echo " CODE_REFERENCE comment specifies: L${start_line}-L${end_line}" + echo " But GitHub URL has different line range" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + fi + else + echo -e "${YELLOW}⚠${NC} No GitHub URL found for reference in ${doc_file}:${line_num}" + echo " Expected rust reference block with GitHub URL" + INVALID_REFS=$((INVALID_REFS + 1)) + EXIT_CODE=1 + fi + fi + done < <(grep -n "CODE_REFERENCE:" "$doc_file" | cut -d: -f1) +done < <(find "$DOCS_DIR" -name "*.md" -o -name "*.mdx") + +echo "" +echo "================================" +echo "Code Reference Verification Summary" +echo "================================" +echo -e "Total references checked: ${TOTAL_REFS}" +echo -e "${GREEN}Valid references: ${VALID_REFS}${NC}" +if [[ $INVALID_REFS -gt 0 ]]; then + echo -e "${RED}Invalid references: ${INVALID_REFS}${NC}" +else + echo -e "${GREEN}Invalid references: ${INVALID_REFS}${NC}" +fi +echo "" + +if [[ $EXIT_CODE -eq 0 ]]; then + echo -e "${GREEN}✓ All code references are valid!${NC}" +else + echo -e "${RED}✗ Some code references are invalid. Please update the documentation.${NC}" +fi + +exit $EXIT_CODE diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 52dcbf14aa..ebf749b020 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -51,6 +51,9 @@ jobs: # - ./github/workflows/lint.yaml toolchain: nightly + - name: Verify code references in documentation + run: bash .github/scripts/verify-code-references.sh + - name: Build documentation run: make docs-build diff --git a/website/docs/developers/documentation-guidelines.md b/website/docs/developers/documentation-guidelines.md new file mode 100644 index 0000000000..6f0a108258 --- /dev/null +++ b/website/docs/developers/documentation-guidelines.md @@ -0,0 +1,124 @@ +--- +sidebar_position: 10 +title: Documentation Guidelines +description: Best practices for writing and maintaining documentation +slug: /developers/documentation-guidelines +--- + +# Documentation Guidelines + +This guide explains how to write and maintain documentation for the Mina Rust +project, including how to reference code from the codebase. Referencing code +from codebases can be useful to check compatibility between implementations. For +instance, we can have pages where the Rust code is compared to the OCaml code to +discuss the differences or similarities. + +## Referencing Code in Documentation + +To keep documentation synchronized with the actual codebase, we use the +[`docusaurus-theme-github-codeblock`](https://github.com/christian-bromann/docusaurus-theme-github-codeblock) +plugin that automatically fetches code from GitHub. + +### How to add code references + +Use this pattern to reference code snippets: + +```` + + +```rust reference title="path/to/file.rs" +https://github.com/o1-labs/mina-rust/blob/develop/path/to/file.rs#LStartLine-LEndLine +``` +```` + +### Example + +Here's a real example from the zkApps documentation: + + + +```rust reference title="ledger/src/scan_state/transaction_logic.rs" +https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L3588-L3592 +``` + +### Components explained + +1. **CODE_REFERENCE comment**: Acts as the source of truth for verification + + ```markdown + + ``` + + - Must match the GitHub URL line range exactly + - Used by CI to verify references are valid + - Path is relative to repository root + +2. **Code block with reference**: Displays the actual code + + ```markdown + (triple backticks)rust reference title="path/to/file.rs" + https://github.com/o1-labs/mina-rust/blob/develop/path/to/file.rs#LStartLine-LEndLine + (triple backticks) + ``` + + - Language: Use appropriate language identifier (`rust`, `toml`, `bash`, + etc.) + - `reference` keyword: Tells the plugin to fetch code from GitHub + - `title`: Optional, shows the file path above the code block + - URL: Full GitHub URL with line range (`#L10-L20`) + +### Verification + +A verification script runs in CI to ensure all code references are valid: + +```bash +bash .github/scripts/verify-code-references.sh +``` + +The script checks: + +- ✓ Referenced files exist +- ✓ Line ranges are valid +- ✓ GitHub URLs match CODE_REFERENCE comments +- ✓ Code blocks have corresponding references +- ✓ Local code matches what's deployed on GitHub + +### When code changes + +If code is added or removed and line numbers shift: + +1. The verification script will detect the mismatch in CI +2. Update the `CODE_REFERENCE` comment with new line numbers +3. Update the GitHub URL with matching line numbers +4. The plugin will automatically fetch the updated code + +### Important: workflow for adding code references + + + +:::caution + +Code references must always point to code that exists on the `develop` branch. +The verification script compares local code with GitHub's `develop` branch. + +::: + + + +**Recommended workflow:** + +1. **First PR**: Implement and merge your code changes to `develop` +2. **Second PR**: Add documentation with code references + +This ensures: + +- Code references are always valid in CI +- Documentation doesn't break due to uncommitted changes +- The plugin can fetch code from GitHub successfully + +**Why separate PRs?** + +- The verification script compares local code with GitHub's `develop` branch +- If code isn't merged yet, the script will fail with a "code mismatch" error +- This prevents documentation from referencing code that doesn't exist on + `develop` diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 74dc08fb69..0fa9227699 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -65,6 +65,8 @@ const config: Config = { ], ], + themes: ['docusaurus-theme-github-codeblock'], + themeConfig: { // Replace with your project's social card diff --git a/website/package-lock.json b/website/package-lock.json index aae6874dda..3b8dd24cbe 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -12,6 +12,7 @@ "@docusaurus/preset-classic": "^3.8.1", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", + "docusaurus-theme-github-codeblock": "^2.0.2", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", "react-dom": "^19.0.0" @@ -7073,6 +7074,15 @@ "node": ">=6" } }, + "node_modules/docusaurus-theme-github-codeblock": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/docusaurus-theme-github-codeblock/-/docusaurus-theme-github-codeblock-2.0.2.tgz", + "integrity": "sha512-H2WoQPWOLjGZO6KS58Gsd+eUVjTFJemkReiSSu9chqokyLc/3Ih3+zPRYfuEZ/HsDvSMIarf7CNcp+Vt+/G+ig==", + "license": "MIT", + "dependencies": { + "@docusaurus/types": "^3.0.0" + } + }, "node_modules/dom-converter": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/dom-converter/-/dom-converter-0.2.0.tgz", diff --git a/website/package.json b/website/package.json index fcdb752c20..187f5c96d8 100644 --- a/website/package.json +++ b/website/package.json @@ -19,6 +19,7 @@ "@docusaurus/preset-classic": "^3.8.1", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", + "docusaurus-theme-github-codeblock": "^2.0.2", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", "react-dom": "^19.0.0" diff --git a/website/sidebars.ts b/website/sidebars.ts index 5652c08099..962b0621d2 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -133,6 +133,13 @@ const sidebars: SidebarsConfig = { 'developers/testing/ocaml-node-tests', ], }, + { + type: 'category', + label: 'Documentation', + items: [ + 'developers/documentation-guidelines', + ], + }, { type: 'category', label: 'Future Work', From 1e331adb26005b4f969e419541939a9c8ae6a80a Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Thu, 2 Oct 2025 16:26:34 +0200 Subject: [PATCH 2/2] CHANGELOG: add description for patch for 1493 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e7025b259..732278d99e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Website**: add "Join devnet" page with instructions for community members to join the devnet program and test the Rust node implementation ([#1425](https://github.com/o1-labs/mina-rust/issues/1425)) +- **Website**: add documentation guidelines + ([#1493](https://github.com/o1-labs/mina-rust/pull/1493)) ### Changed