diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index b111185..29b1edc 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -1,6 +1,12 @@ name: Publish Documentation -on: workflow_dispatch +on: + push: + branches: + - main + pull_request: + branches: + - main jobs: build-and-deploy-docs: diff --git a/docs/.gitignore b/docs/.gitignore index 7d00bc5..0d9151b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,7 @@ # Sphinx build outputs _build/ -_build_simple/ +_build_*/ +_static/ # Sphinx auto-generated files _autosummary/ diff --git a/docs/build_docs.py b/docs/build_docs.py index fed007c..3f037aa 100644 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -10,10 +10,10 @@ from pathlib import Path def run_command(cmd, cwd=None): - """Run a shell command and return the result.""" try: + """Run a shell command and return the result.""" + try: result = subprocess.run( - cmd, shell=True, check=True, cwd=cwd, - capture_output=True, text=True + 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: @@ -33,19 +33,21 @@ def build_docs(source_dir, build_dir, watch=False): 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") + 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" @@ -63,13 +65,13 @@ def serve_docs(build_dir, port=8000): 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 @@ -77,79 +79,83 @@ 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", + "command", choices=["build", "clean", "serve", "watch", "check"], - help="Command to execute" + help="Command to execute", ) parser.add_argument( - "--port", "-p", + "--port", + "-p", type=int, default=8000, - help="Port for serving documentation (default: 8000)" + help="Port for serving documentation (default: 8000)", ) parser.add_argument( - "--open", "-o", + "--open", + "-o", action="store_true", - help="Open documentation in browser after building/serving" + 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) diff --git a/docs/index.md b/docs/index.md index 2172b58..4b45af4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,6 @@ Welcome to **tzst**, the next-generation Python library engineered for modern ar quickstart api/index examples -changelog ``` ## What is tzst?