blob: bd50efa81b3a51f4cb351d6e7bb6d12096010aa1 [file]
#!/usr/bin/env python3
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You 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.
"""
Start the Docusaurus development server, freeing its port first.
Full docs: start-docusaurus.md
"""
import json
import os
import shutil
import subprocess
import sys
import time
from pathlib import Path
def print_step(message):
"""Print a step message with emoji."""
print(f"{message}")
def resolve_javadocs_version(docs_dir):
"""Resolve the current javadocs version robustly for the apidocs symlink.
Prefers the latest entry in static/javadocs/releases.json that has a matching
committed static/javadocs/<version>/ directory; falls back to the sole versioned
directory when the index is unavailable. Returns None if none can be determined.
"""
javadocs_dir = docs_dir / "static" / "javadocs"
releases_json = javadocs_dir / "releases.json"
def version_key(v):
try:
return tuple(int(p) if p.isdigit() else p for p in v.split('.'))
except (ValueError, AttributeError):
return v
if releases_json.is_file():
try:
with open(releases_json) as f:
releases = json.load(f)
versions = [r.get("version") for r in releases if r.get("version")]
versions = [v for v in versions if (javadocs_dir / v).is_dir()]
if versions:
versions.sort(key=version_key, reverse=True)
return versions[0]
except Exception as e:
print_step(f"⚠️ Could not read {releases_json}: {e}")
if javadocs_dir.is_dir():
subdirs = [d.name for d in javadocs_dir.iterdir()
if d.is_dir() and d.name[:1].isdigit()]
if len(subdirs) == 1:
return subdirs[0]
return None
def ensure_apidocs_symlink(docs_dir):
"""Point static/site/apidocs at the committed static/javadocs/<version> tree.
Creates a RELATIVE symlink (target '../javadocs/<version>') so the unversioned
/site/apidocs/... links resolve against the committed javadocs with no Maven build.
Idempotent, replaces an existing real directory, and skips (with a warning) when the
committed javadocs are missing rather than failing startup.
"""
version = resolve_javadocs_version(docs_dir)
if not version:
print_step("⚠️ Could not resolve javadocs version — skipping apidocs symlink")
return
static_site = docs_dir / "static" / "site"
apidocs = static_site / "apidocs"
target = os.path.join("..", "javadocs", version)
versioned = docs_dir / "static" / "javadocs" / version
if not versioned.is_dir():
print_step(f"⚠️ Committed javadocs not found at {versioned} — skipping apidocs symlink")
return
static_site.mkdir(parents=True, exist_ok=True)
if apidocs.is_symlink():
if os.readlink(apidocs) == target:
print_step(f"🔗 apidocs already links to {target}")
return
apidocs.unlink()
elif apidocs.is_dir():
shutil.rmtree(apidocs)
elif apidocs.exists():
apidocs.unlink()
os.symlink(target, apidocs)
print_step(f"🔗 Linked static/site/apidocs -> {target}")
def kill_port_3000():
"""Kill any process running on port 3000."""
print_step("🔍 Checking for existing processes on port 3000...")
try:
# Try lsof first (macOS/Linux)
result = subprocess.run(
["lsof", "-ti:3000"],
capture_output=True,
text=True
)
if result.stdout.strip():
pids = result.stdout.strip().split('\n')
for pid in pids:
if pid:
print_step(f"⚡ Killing existing process on port 3000 (PID: {pid})")
try:
subprocess.run(["kill", "-9", pid], check=False)
except Exception:
pass
time.sleep(2)
except FileNotFoundError:
# lsof not available, try netstat (Windows/some Linux)
try:
if sys.platform == "win32":
# Windows: use netstat
result = subprocess.run(
["netstat", "-ano"],
capture_output=True,
text=True
)
for line in result.stdout.split('\n'):
if ':3000' in line and 'LISTENING' in line:
parts = line.split()
pid = parts[-1]
print_step(f"⚡ Killing existing process on port 3000 (PID: {pid})")
subprocess.run(["taskkill", "/F", "/PID", pid], check=False)
time.sleep(2)
break
except Exception:
# If all fails, just continue
pass
def clear_caches(docs_dir):
"""Clear Docusaurus caches."""
print_step("🧹 Clearing cache...")
cache_dirs = [
docs_dir / ".docusaurus",
docs_dir / "build",
docs_dir / "node_modules" / ".cache"
]
for cache_dir in cache_dirs:
if cache_dir.exists():
try:
shutil.rmtree(cache_dir)
print(f" Removed: {cache_dir.name}")
except Exception as e:
print(f" Warning: Could not remove {cache_dir.name}: {e}")
def install_dependencies(docs_dir):
"""Install npm dependencies if node_modules doesn't exist."""
node_modules = docs_dir / "node_modules"
if not node_modules.exists():
print_step("📦 Installing dependencies (this may take a few minutes)...")
try:
subprocess.run(
["npm", "install"],
cwd=docs_dir,
check=True
)
print_step("✅ Dependencies installed successfully")
except subprocess.CalledProcessError:
print("❌ ERROR: Failed to install dependencies")
return False
return True
def main():
import argparse
parser = argparse.ArgumentParser(description='Start Docusaurus dev server')
parser.add_argument('--clean', action='store_true',
help='Clear .docusaurus/, build/, and node_modules/.cache before starting')
args = parser.parse_args()
# Get directories
script_dir = Path(__file__).parent
docs_dir = script_dir.parent # docs/
print_step("🔄 Starting Docusaurus server...")
print_step(f"📁 Working directory: {docs_dir}")
# Verify package.json exists
package_json = docs_dir / "package.json"
if not package_json.exists():
print(f"❌ ERROR: package.json not found in {docs_dir}")
return 1
# Install dependencies if needed
if not install_dependencies(docs_dir):
return 1
# Only kill port 3000 if the dev-server lock file is NOT present.
# If the lock file exists, another instance of the server is intentionally
# running and we should not terminate it.
lock_file_check = docs_dir / '.dev-server-running'
if lock_file_check.exists():
print("⚠️ Dev server lock file found — another instance is already running. Exiting to avoid cache conflicts.")
return 0
kill_port_3000()
# Clear caches only when explicitly requested
if args.clean:
clear_caches(docs_dir)
# Point static/site/apidocs at the committed javadocs so /site/apidocs/... links
# work with no Maven build. Non-fatal if the committed javadocs are missing.
ensure_apidocs_symlink(docs_dir)
# Start the server
print_step("🚀 Starting Docusaurus server...")
print()
# Write a lock file so build-docs.py knows the dev server is running
# and skips the production Docusaurus build to avoid webpack cache conflicts.
lock_file = docs_dir / '.dev-server-running'
lock_file.touch()
try:
subprocess.run(
["npm", "start"],
cwd=docs_dir,
check=True
)
except subprocess.CalledProcessError:
print()
print("❌ ERROR: Failed to start Docusaurus server")
return 1
except KeyboardInterrupt:
print()
print("🛑 Server stopped by user")
return 0
finally:
# Remove the lock file when the server stops
try:
lock_file.unlink(missing_ok=True)
except Exception:
pass
return 0
if __name__ == "__main__":
sys.exit(main())