Skip to content

Commit bbda8c5

Browse files
mbarbinmbarbin
committed
Wip integration of markdown api in Docusaurus site
1 parent 4e90ff0 commit bbda8c5

File tree

3 files changed

+178
-0
lines changed

3 files changed

+178
-0
lines changed

‎doc/docs/reference/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ocaml-api/

‎doc/sidebars.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ const sidebars: SidebarsConfig = {
5252
{ type: 'doc', id: 'reference/crs-actions-config/README', label: 'CRs Actions Config' },
5353
{ type: 'doc', id: 'reference/crs-ignore-files/README', label: 'CRs Ignore Files' },
5454
{ type: 'doc', id: 'reference/odoc', label: 'OCaml Packages' },
55+
{
56+
type: 'autogenerated',
57+
dirName: 'reference/ocaml-api',
58+
},
5559
],
5660
},
5761
],

‎doc/update-ocaml-docs.sh

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
#!/bin/bash
2+
3+
# Script to update OCaml documentation in Docusaurus
4+
# Can be run from project root or doc/ directory
5+
# Usage: ./update-ocaml-docs.sh [--yes]
6+
7+
set -euo pipefail
8+
9+
# Parse command line arguments
10+
AUTO_YES=false
11+
if [[ "${1:-}" == "--yes" ]]; then
12+
AUTO_YES=true
13+
fi
14+
15+
# Helper function for interactive prompts
16+
prompt_user() {
17+
local message="$1"
18+
if [[ "$AUTO_YES" == "true" ]]; then
19+
echo "$message (Y/n) y"
20+
return 0
21+
fi
22+
23+
echo -n "$message (Y/n) "
24+
read -r response
25+
case "$response" in
26+
[nN]|[nN][oO]) return 1 ;;
27+
*) return 0 ;;
28+
esac
29+
}
30+
31+
# Get the directory where this script is located
32+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
33+
34+
# Determine project root and doc directory based on script location
35+
# The script is always in doc/, so project root is one level up
36+
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
37+
DOC_DIR="$SCRIPT_DIR"
38+
39+
# Verify we have the correct directories
40+
if [[ ! -f "$PROJECT_ROOT/dune-project" ]] || [[ ! -f "$DOC_DIR/docusaurus.config.ts" ]]; then
41+
echo "Error: Could not locate project structure relative to script location"
42+
echo "Expected: $PROJECT_ROOT/dune-project and $DOC_DIR/docusaurus.config.ts"
43+
exit 1
44+
fi
45+
46+
echo "🔧 Updating OCaml documentation for Docusaurus..."
47+
echo " Project root: $PROJECT_ROOT"
48+
echo " Doc directory: $DOC_DIR"
49+
50+
# Step 1: Generate/check OCaml markdown documentation
51+
echo "📚 Checking for OCaml documentation..."
52+
53+
# Check if files exist and offer to regenerate
54+
if [[ -d "$PROJECT_ROOT/_build/default/_doc/_markdown" ]]; then
55+
file_count=$(find "$PROJECT_ROOT/_build/default/_doc/_markdown" -name "*.md" | wc -l)
56+
echo " ✓ Found $file_count existing markdown files"
57+
58+
echo ""
59+
if ! prompt_user "🔄 Regenerate OCaml documentation with dune build @doc-markdown?"; then
60+
echo " Using existing documentation files."
61+
else
62+
echo " 📝 Regenerating OCaml documentation..."
63+
echo " Running: dune build @doc-markdown"
64+
cd "$PROJECT_ROOT"
65+
if dune build @doc-markdown; then
66+
echo " ✓ Documentation regenerated successfully"
67+
# Recount files after generation
68+
file_count=$(find "_build/default/_doc/_markdown" -name "*.md" | wc -l)
69+
echo " ✓ Generated $file_count markdown files"
70+
else
71+
echo " ⚠️ Documentation generation had some failures, checking results..."
72+
new_file_count=$(find "_build/default/_doc/_markdown" -name "*.md" 2>/dev/null | wc -l)
73+
if [[ $new_file_count -gt 0 ]]; then
74+
echo " ✓ Found $new_file_count markdown files despite some failures"
75+
if ! prompt_user "Continue with partial documentation?"; then
76+
echo " ❌ Aborted by user"
77+
exit 1
78+
fi
79+
file_count=$new_file_count
80+
else
81+
echo " ❌ No documentation files generated"
82+
exit 1
83+
fi
84+
fi
85+
fi
86+
else
87+
echo " ⚠️ No generated documentation found"
88+
if ! prompt_user "Generate OCaml documentation with dune build @doc-markdown?"; then
89+
echo " ❌ Aborted by user"
90+
exit 1
91+
fi
92+
93+
echo " 📝 Generating OCaml documentation..."
94+
echo " Running: dune build @doc-markdown"
95+
cd "$PROJECT_ROOT"
96+
if dune build @doc-markdown; then
97+
echo " ✓ Documentation generated successfully"
98+
# Count files after generation
99+
if [[ -d "_build/default/_doc/_markdown" ]]; then
100+
file_count=$(find "_build/default/_doc/_markdown" -name "*.md" | wc -l)
101+
echo " ✓ Generated $file_count markdown files"
102+
else
103+
echo " ❌ Generation completed but no files found"
104+
exit 1
105+
fi
106+
else
107+
echo " ⚠️ Documentation generation had some failures, checking results..."
108+
if [[ -d "_build/default/_doc/_markdown" ]]; then
109+
file_count=$(find "_build/default/_doc/_markdown" -name "*.md" | wc -l)
110+
if [[ $file_count -gt 0 ]]; then
111+
echo " ✓ Found $file_count markdown files despite some failures"
112+
if ! prompt_user "Continue with partial documentation?"; then
113+
echo " ❌ Aborted by user"
114+
exit 1
115+
fi
116+
else
117+
echo " ❌ No documentation files generated"
118+
exit 1
119+
fi
120+
else
121+
echo " ❌ Documentation generation failed completely"
122+
exit 1
123+
fi
124+
fi
125+
fi
126+
127+
# Step 2: Reset and create target directory
128+
echo ""
129+
if ! prompt_user "📁 Reset and copy OCaml documentation to Docusaurus?"; then
130+
echo " ❌ Aborted by user"
131+
exit 1
132+
fi
133+
134+
echo "📁 Resetting target directory..."
135+
echo " Running: rm -rf $DOC_DIR/docs/reference/ocaml-api"
136+
rm -rf "$DOC_DIR/docs/reference/ocaml-api"
137+
echo " Running: mkdir -p $DOC_DIR/docs/reference/ocaml-api"
138+
mkdir -p "$DOC_DIR/docs/reference/ocaml-api"
139+
140+
# Step 3: Copy generated files
141+
echo "📋 Copying generated markdown files..."
142+
echo " Running: cp -r $PROJECT_ROOT/_build/default/_doc/_markdown/* $DOC_DIR/docs/reference/ocaml-api/"
143+
cp -r "$PROJECT_ROOT/_build/default/_doc/_markdown"/* "$DOC_DIR/docs/reference/ocaml-api/"
144+
145+
# Step 4: Set proper permissions (in case source files are read-only)
146+
echo "🔐 Setting file permissions..."
147+
echo " Running: find $DOC_DIR/docs/reference/ocaml-api -type f -exec chmod 644 {} \;"
148+
find "$DOC_DIR/docs/reference/ocaml-api" -type f -exec chmod 644 {} \;
149+
150+
echo "✅ OCaml documentation updated successfully!"
151+
echo " Files copied to: $DOC_DIR/docs/reference/ocaml-api/"
152+
153+
# Step 5: Optional build step
154+
echo ""
155+
if ! prompt_user "🚀 Build the Docusaurus site now?"; then
156+
echo " ❌ Aborted by user"
157+
exit 1
158+
fi
159+
160+
echo "🚀 Building Docusaurus site..."
161+
echo " Running: cd $DOC_DIR && npm run build"
162+
cd "$DOC_DIR"
163+
if npm run build; then
164+
echo ""
165+
echo "📖 Documentation site ready!"
166+
echo " • For development (live reload): npm run start"
167+
echo " • To serve built site: npm run serve"
168+
echo " • Built files are in: $DOC_DIR/build/"
169+
else
170+
echo ""
171+
echo "⚠️ Build failed, but documentation files were copied successfully."
172+
echo " You can manually run 'npm run build' from the doc directory to debug."
173+
fi

0 commit comments

Comments
 (0)