Skip to content

Commit 78393db

Browse files
lyzhang0113lyzhang0113
committed
Add cross-platform local dev scripts with script docs
1 parent e002ddb commit 78393db

3 files changed

Lines changed: 377 additions & 0 deletions

File tree

‎scripts/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Development Scripts
2+
3+
This folder contains local development setup scripts for this repository:
4+
5+
- `dev.ps1`: Windows PowerShell workflow
6+
- `dev.sh`: Linux/WSL Bash workflow
7+
8+
Both scripts do the same high-level flow:
9+
10+
1. Prepare a local `.dev/` workspace in this repo.
11+
2. Clone or sync `Docs-Template-Repo` into `.dev/Docs-Template-Repo`.
12+
3. Build a merged workspace in `.dev/DocHome` (docs + template).
13+
4. Replace `assetsPath` values in `_includes` and `_layouts`.
14+
5. Install gems with Bundler using local cache directories under `.dev/`.
15+
6. Run `jekyll serve` (or print the serve command when no-serve mode is used).
16+
17+
## Windows (`dev.ps1`)
18+
19+
Run from repo root:
20+
21+
```powershell
22+
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1
23+
```
24+
25+
Useful options:
26+
27+
```powershell
28+
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 -NoServe
29+
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 -NoTemplateUpdate
30+
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 -Port 6001
31+
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 -BindHost 0.0.0.0
32+
```
33+
34+
## Linux / WSL (`dev.sh`)
35+
36+
Run from repo root:
37+
38+
```bash
39+
bash ./scripts/dev.sh
40+
```
41+
42+
Useful options:
43+
44+
```bash
45+
bash ./scripts/dev.sh --no-serve
46+
bash ./scripts/dev.sh --no-template-update
47+
bash ./scripts/dev.sh --port 6001
48+
bash ./scripts/dev.sh --bind-host 0.0.0.0
49+
```
50+
51+
## Output
52+
53+
Default local URL root after start:
54+
55+
```text
56+
http://localhost:5555/web-twain/docs/
57+
```

‎scripts/dev.ps1‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
[CmdletBinding()]
2+
param(
3+
[string]$TemplateRepoUrl = "https://github.com/dynamsoft-docs/Docs-Template-Repo.git",
4+
[string]$TemplateBranch = "preview",
5+
[int]$Port = 5555,
6+
[string]$BindHost = "localhost",
7+
[switch]$NoTemplateUpdate,
8+
[switch]$NoServe
9+
)
10+
11+
Set-StrictMode -Version Latest
12+
$ErrorActionPreference = "Stop"
13+
14+
function Write-Step {
15+
param([string]$Message)
16+
Write-Host "==> $Message"
17+
}
18+
19+
function Ensure-Command {
20+
param([string]$Name)
21+
if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
22+
throw "Required command '$Name' was not found in PATH."
23+
}
24+
}
25+
26+
function Invoke-Native {
27+
param(
28+
[Parameter(Mandatory = $true)]
29+
[string]$FilePath,
30+
[string[]]$Arguments = @()
31+
)
32+
33+
& $FilePath @Arguments
34+
$code = $LASTEXITCODE
35+
if ($code -ne 0) {
36+
$argText = ($Arguments -join " ")
37+
throw "Command failed with exit code ${code}: $FilePath $argText"
38+
}
39+
}
40+
41+
function Invoke-Robocopy {
42+
param(
43+
[string]$Source,
44+
[string]$Destination,
45+
[string[]]$ExtraArgs
46+
)
47+
48+
$baseArgs = @(
49+
$Source,
50+
$Destination,
51+
"/R:2",
52+
"/W:2",
53+
"/NFL",
54+
"/NDL",
55+
"/NJH",
56+
"/NJS",
57+
"/NP"
58+
)
59+
$allArgs = $baseArgs + $ExtraArgs
60+
& robocopy @allArgs | Out-Null
61+
$code = $LASTEXITCODE
62+
if ($code -ge 8) {
63+
throw "robocopy failed with exit code $code. Source: $Source Destination: $Destination"
64+
}
65+
}
66+
67+
Ensure-Command "git"
68+
Ensure-Command "robocopy"
69+
Ensure-Command "bundle"
70+
71+
$repoRoot = Split-Path -Parent $PSScriptRoot
72+
$devRoot = Join-Path $repoRoot ".dev"
73+
$templateRoot = Join-Path $devRoot "Docs-Template-Repo"
74+
$docHome = Join-Path $devRoot "DocHome"
75+
$bundlePath = Join-Path $devRoot "vendor\bundle"
76+
$bundleConfig = Join-Path $devRoot ".bundle"
77+
$bundleUserHome = Join-Path $devRoot ".bundle-user"
78+
$jekyllCache = Join-Path $devRoot ".jekyll-cache"
79+
$siteDir = Join-Path $devRoot "_site"
80+
81+
Write-Step "Preparing local workspace in $devRoot"
82+
New-Item -ItemType Directory -Force -Path $devRoot | Out-Null
83+
84+
if (-not (Test-Path $templateRoot)) {
85+
Write-Step "Cloning template repo ($TemplateBranch)"
86+
Invoke-Native -FilePath "git" -Arguments @("clone", "--depth", "1", "--branch", $TemplateBranch, $TemplateRepoUrl, $templateRoot)
87+
} elseif (-not $NoTemplateUpdate) {
88+
Write-Step "Syncing template repo ($TemplateBranch)"
89+
Invoke-Native -FilePath "git" -Arguments @("-C", $templateRoot, "fetch", "origin", $TemplateBranch, "--depth", "1")
90+
Invoke-Native -FilePath "git" -Arguments @("-C", $templateRoot, "reset", "--hard")
91+
Invoke-Native -FilePath "git" -Arguments @("-C", $templateRoot, "clean", "-fd")
92+
Invoke-Native -FilePath "git" -Arguments @("-C", $templateRoot, "checkout", "-B", $TemplateBranch, "origin/$TemplateBranch")
93+
} else {
94+
Write-Step "Skipping template update"
95+
}
96+
97+
Write-Step "Rebuilding merged site workspace"
98+
New-Item -ItemType Directory -Force -Path $docHome | Out-Null
99+
Invoke-Robocopy -Source $repoRoot -Destination $docHome -ExtraArgs @(
100+
"/MIR",
101+
"/XD", ".git", ".dev", ".vs", "node_modules", "_site", ".bundle", ".jekyll-cache", ".sass-cache", "vendor"
102+
)
103+
Invoke-Robocopy -Source $templateRoot -Destination $docHome -ExtraArgs @(
104+
"/E",
105+
"/XD", ".git", ".github", "_site", "node_modules"
106+
)
107+
108+
Write-Step "Applying local assetsPath replacements"
109+
$search = "assetsPath = '/webres/wwwroot'"
110+
$replace = "assetsPath = 'https://www.dynamsoft.com/webres/wwwroot'"
111+
foreach ($dirName in @("_includes", "_layouts")) {
112+
$dirPath = Join-Path $docHome $dirName
113+
if (-not (Test-Path $dirPath)) {
114+
continue
115+
}
116+
117+
Get-ChildItem -Path $dirPath -Recurse -File | ForEach-Object {
118+
$path = $_.FullName
119+
try {
120+
$content = [System.IO.File]::ReadAllText($path)
121+
} catch {
122+
return
123+
}
124+
if ($content.Contains($search)) {
125+
$updated = $content.Replace($search, $replace)
126+
[System.IO.File]::WriteAllText($path, $updated)
127+
}
128+
}
129+
}
130+
131+
Write-Step "Configuring Bundler and Jekyll local paths"
132+
$env:BUNDLE_PATH = $bundlePath
133+
$env:BUNDLE_APP_CONFIG = $bundleConfig
134+
$env:BUNDLE_USER_HOME = $bundleUserHome
135+
$env:BUNDLE_USER_CACHE = Join-Path $bundleUserHome "cache"
136+
$env:JEKYLL_CACHE_DIR = $jekyllCache
137+
$env:JEKYLL_ENV = "development"
138+
New-Item -ItemType Directory -Force -Path $bundlePath, $bundleConfig, $bundleUserHome, $jekyllCache, $siteDir | Out-Null
139+
140+
Push-Location $docHome
141+
try {
142+
Write-Step "Installing Ruby dependencies"
143+
Invoke-Native -FilePath "bundle" -Arguments @("install")
144+
145+
if ($NoServe) {
146+
Write-Step "Build workspace prepared. Start server with:"
147+
Write-Host "bundle exec jekyll serve -P $Port --trace --host=$BindHost --livereload --destination `"$siteDir`""
148+
} else {
149+
Write-Step "Starting Jekyll server on port $Port"
150+
Invoke-Native -FilePath "bundle" -Arguments @("exec", "jekyll", "serve", "-P", "$Port", "--trace", "--host=$BindHost", "--livereload", "--destination", "$siteDir")
151+
}
152+
} finally {
153+
Pop-Location
154+
}
155+
156+

‎scripts/dev.sh‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
#!/usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
template_repo_url="https://github.com/dynamsoft-docs/Docs-Template-Repo.git"
6+
template_branch="preview"
7+
port="5555"
8+
bind_host="localhost"
9+
no_template_update="false"
10+
no_serve="false"
11+
12+
write_step() {
13+
echo "==> $1"
14+
}
15+
16+
require_cmd() {
17+
if ! command -v "$1" >/dev/null 2>&1; then
18+
echo "Required command '$1' was not found in PATH." >&2
19+
exit 1
20+
fi
21+
}
22+
23+
show_help() {
24+
cat <<'EOF'
25+
Usage: ./scripts/dev.sh [options]
26+
27+
Options:
28+
--template-repo-url URL Template repository URL
29+
--template-branch NAME Template branch (default: preview)
30+
--port N Jekyll port (default: 5555)
31+
--bind-host HOST Jekyll bind host (default: localhost)
32+
--no-template-update Skip template fetch/pull
33+
--no-serve Prepare workspace only (do not start Jekyll)
34+
-h, --help Show this help message
35+
EOF
36+
}
37+
38+
while [[ $# -gt 0 ]]; do
39+
case "$1" in
40+
--template-repo-url)
41+
template_repo_url="${2:-}"
42+
shift 2
43+
;;
44+
--template-branch)
45+
template_branch="${2:-}"
46+
shift 2
47+
;;
48+
--port)
49+
port="${2:-}"
50+
shift 2
51+
;;
52+
--bind-host)
53+
bind_host="${2:-}"
54+
shift 2
55+
;;
56+
--no-template-update)
57+
no_template_update="true"
58+
shift
59+
;;
60+
--no-serve)
61+
no_serve="true"
62+
shift
63+
;;
64+
-h|--help)
65+
show_help
66+
exit 0
67+
;;
68+
*)
69+
echo "Unknown option: $1" >&2
70+
show_help
71+
exit 1
72+
;;
73+
esac
74+
done
75+
76+
require_cmd git
77+
require_cmd rsync
78+
require_cmd bundle
79+
require_cmd find
80+
require_cmd sed
81+
82+
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
83+
repo_root="$(cd -- "$script_dir/.." && pwd)"
84+
dev_root="$repo_root/.dev"
85+
template_root="$dev_root/Docs-Template-Repo"
86+
doc_home="$dev_root/DocHome"
87+
bundle_path="$dev_root/vendor/bundle"
88+
bundle_config="$dev_root/.bundle"
89+
bundle_user_home="$dev_root/.bundle-user"
90+
jekyll_cache="$dev_root/.jekyll-cache"
91+
site_dir="$dev_root/_site"
92+
93+
write_step "Preparing local workspace in $dev_root"
94+
mkdir -p "$dev_root"
95+
96+
if [[ ! -d "$template_root/.git" ]]; then
97+
write_step "Cloning template repo ($template_branch)"
98+
git clone --depth 1 --branch "$template_branch" "$template_repo_url" "$template_root"
99+
elif [[ "$no_template_update" != "true" ]]; then
100+
write_step "Syncing template repo ($template_branch)"
101+
git -C "$template_root" fetch origin "$template_branch" --depth 1
102+
git -C "$template_root" reset --hard
103+
git -C "$template_root" clean -fd
104+
git -C "$template_root" checkout -B "$template_branch" "origin/$template_branch"
105+
else
106+
write_step "Skipping template update"
107+
fi
108+
109+
write_step "Rebuilding merged site workspace"
110+
rm -rf "$doc_home"
111+
mkdir -p "$doc_home"
112+
rsync -a --delete \
113+
--exclude '.git' \
114+
--exclude '.dev' \
115+
--exclude '.vs' \
116+
--exclude 'node_modules' \
117+
--exclude '_site' \
118+
--exclude '.bundle' \
119+
--exclude '.jekyll-cache' \
120+
--exclude '.sass-cache' \
121+
--exclude 'vendor' \
122+
"$repo_root"/ "$doc_home"/
123+
rsync -a \
124+
--exclude '.git' \
125+
--exclude '.github' \
126+
--exclude '_site' \
127+
--exclude 'node_modules' \
128+
"$template_root"/ "$doc_home"/
129+
130+
write_step "Applying local assetsPath replacements"
131+
search="assetsPath = '/webres/wwwroot'"
132+
replace="assetsPath = 'https://www.dynamsoft.com/webres/wwwroot'"
133+
for dir_name in "_includes" "_layouts"; do
134+
dir_path="$doc_home/$dir_name"
135+
if [[ ! -d "$dir_path" ]]; then
136+
continue
137+
fi
138+
139+
while IFS= read -r -d '' file_path; do
140+
sed -i "s|$search|$replace|g" "$file_path"
141+
done < <(find "$dir_path" -type f -print0)
142+
done
143+
144+
write_step "Configuring Bundler and Jekyll local paths"
145+
export BUNDLE_PATH="$bundle_path"
146+
export BUNDLE_APP_CONFIG="$bundle_config"
147+
export BUNDLE_USER_HOME="$bundle_user_home"
148+
export BUNDLE_USER_CACHE="$bundle_user_home/cache"
149+
export JEKYLL_CACHE_DIR="$jekyll_cache"
150+
export JEKYLL_ENV="development"
151+
mkdir -p "$bundle_path" "$bundle_config" "$bundle_user_home" "$jekyll_cache" "$site_dir"
152+
153+
pushd "$doc_home" >/dev/null
154+
write_step "Installing Ruby dependencies"
155+
bundle install
156+
157+
if [[ "$no_serve" == "true" ]]; then
158+
write_step "Build workspace prepared. Start server with:"
159+
echo "bundle exec jekyll serve -P $port --trace --host=$bind_host --livereload --destination \"$site_dir\""
160+
else
161+
write_step "Starting Jekyll server on port $port"
162+
bundle exec jekyll serve -P "$port" --trace --host="$bind_host" --livereload --destination "$site_dir"
163+
fi
164+
popd >/dev/null

0 commit comments

Comments
 (0)