xixu-me
cfb8290dea
- Complete documentation structure with index, quickstart, examples, and API reference - Sphinx configuration with RTD theme, MyST parser, and autodoc - GitHub Actions workflow for automated documentation building and deployment - Local development tools (Makefile, build scripts) - Comprehensive examples covering basic usage, security, and performance - API documentation for core, CLI, and exceptions modules
159 lines
4.6 KiB
Python
159 lines
4.6 KiB
Python
#!/usr/bin/env python3
|
|
"""Development script for building and serving documentation locally."""
|
|
|
|
import argparse
|
|
import os
|
|
import shutil
|
|
import subprocess
|
|
import sys
|
|
import webbrowser
|
|
from pathlib import Path
|
|
|
|
|
|
def run_command(cmd, cwd=None):
|
|
"""Run a shell command and return the result.""" try:
|
|
result = subprocess.run(
|
|
cmd, shell=True, check=True, cwd=cwd,
|
|
capture_output=True, text=True
|
|
)
|
|
return result.returncode == 0, result.stdout, result.stderr
|
|
except subprocess.CalledProcessError as e:
|
|
return False, e.stdout, e.stderr
|
|
|
|
|
|
def clean_build(build_dir):
|
|
"""Clean the build directory."""
|
|
if build_dir.exists():
|
|
print(f"Cleaning {build_dir}")
|
|
shutil.rmtree(build_dir)
|
|
|
|
|
|
def build_docs(source_dir, build_dir, watch=False):
|
|
"""Build the documentation."""
|
|
if watch:
|
|
print("Starting live reload server...")
|
|
print("Visit http://localhost:8000 to view the documentation")
|
|
print("Press Ctrl+C to stop the server")
|
|
|
|
cmd = f"sphinx-autobuild {source_dir} {build_dir} --host 0.0.0.0 --port 8000"
|
|
success, stdout, stderr = run_command(cmd)
|
|
|
|
if not success:
|
|
print("Failed to start live reload server.")
|
|
print("Make sure sphinx-autobuild is installed: pip install sphinx-autobuild")
|
|
return False
|
|
else:
|
|
print(f"Building documentation: {source_dir} -> {build_dir}")
|
|
cmd = f"python -m sphinx -b html {source_dir} {build_dir}"
|
|
success, stdout, stderr = run_command(cmd)
|
|
|
|
if success:
|
|
print("Documentation built successfully!")
|
|
index_file = build_dir / "index.html"
|
|
print(f"Open {index_file} in your browser to view the documentation")
|
|
return True
|
|
else:
|
|
print("Build failed!")
|
|
print("STDOUT:", stdout)
|
|
print("STDERR:", stderr)
|
|
return False
|
|
|
|
|
|
def serve_docs(build_dir, port=8000):
|
|
"""Serve the built documentation locally."""
|
|
if not build_dir.exists():
|
|
print(f"Build directory {build_dir} does not exist. Build the docs first.")
|
|
return False
|
|
|
|
print(f"Serving documentation at http://localhost:{port}")
|
|
print("Press Ctrl+C to stop the server")
|
|
|
|
cmd = f"python -m http.server {port}"
|
|
success, stdout, stderr = run_command(cmd, cwd=build_dir)
|
|
|
|
return success
|
|
|
|
|
|
def check_dependencies():
|
|
"""Check if required dependencies are installed."""
|
|
try:
|
|
import sphinx
|
|
print(f"Sphinx version: {sphinx.__version__}")
|
|
except ImportError:
|
|
print("Sphinx is not installed. Install with: pip install sphinx")
|
|
return False
|
|
|
|
try:
|
|
import tzst
|
|
print(f"tzst version: {tzst.__version__}")
|
|
except ImportError:
|
|
print("tzst package is not installed. Install with: pip install -e ..")
|
|
return False
|
|
|
|
return True
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description="Build and serve tzst documentation")
|
|
parser.add_argument(
|
|
"command",
|
|
choices=["build", "clean", "serve", "watch", "check"],
|
|
help="Command to execute"
|
|
)
|
|
parser.add_argument(
|
|
"--port", "-p",
|
|
type=int,
|
|
default=8000,
|
|
help="Port for serving documentation (default: 8000)"
|
|
)
|
|
parser.add_argument(
|
|
"--open", "-o",
|
|
action="store_true",
|
|
help="Open documentation in browser after building/serving"
|
|
)
|
|
|
|
args = parser.parse_args()
|
|
|
|
# Get directories
|
|
script_dir = Path(__file__).parent
|
|
source_dir = script_dir
|
|
build_dir = script_dir / "_build"
|
|
|
|
if args.command == "check":
|
|
success = check_dependencies()
|
|
sys.exit(0 if success else 1)
|
|
|
|
elif args.command == "clean":
|
|
clean_build(build_dir)
|
|
|
|
elif args.command == "build":
|
|
if not check_dependencies():
|
|
sys.exit(1)
|
|
|
|
success = build_docs(source_dir, build_dir)
|
|
|
|
if success and args.open:
|
|
index_file = build_dir / "index.html"
|
|
webbrowser.open(f"file://{index_file.absolute()}")
|
|
|
|
sys.exit(0 if success else 1)
|
|
|
|
elif args.command == "watch":
|
|
if not check_dependencies():
|
|
sys.exit(1)
|
|
|
|
success = build_docs(source_dir, build_dir, watch=True)
|
|
sys.exit(0 if success else 1)
|
|
|
|
elif args.command == "serve":
|
|
success = serve_docs(build_dir, args.port)
|
|
|
|
if args.open:
|
|
webbrowser.open(f"http://localhost:{args.port}")
|
|
|
|
sys.exit(0 if success else 1)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|