#!/usr/bin/env python3 """ Generate Python API documentation for all workspace packages using pdoc3. This script generates HTML documentation for all Python packages in the Core Lightning workspace and creates an index page linking to all of them. """ import os import subprocess import sys from datetime import datetime from pathlib import Path # Define packages to document (module name -> source directory) # Only includes packages that are in the workspace and can be imported PACKAGES = { "pyln.client": "contrib/pyln-client", "pyln.proto": "contrib/pyln-proto", "pyln.grpc": "contrib/pyln-grpc-proto", "pyln.testing": "contrib/pyln-testing", "pyln.spec.bolt7": "contrib/pyln-spec/bolt7", } INDEX_HTML_TEMPLATE = """ Core Lightning Python Packages Documentation

Core Lightning Python Packages Documentation

This page provides links to the API documentation for all Python packages in the Core Lightning workspace.

pyln.client

Client library and plugin library for Core Lightning

pyln.proto

Lightning Network protocol implementation

pyln.grpc

gRPC protocol definitions for Core Lightning

pyln.testing

Testing utilities for Core Lightning

pyln.spec.bolt7

BOLT #7 specification implementation

Generated on {timestamp}

""" def generate_docs(output_dir: Path, repo_root: Path): """Generate documentation for all packages.""" print(f"Generating Python documentation for all workspace packages...") print(f"Output directory: {output_dir}") # Clean and create output directory if output_dir.exists(): import shutil shutil.rmtree(output_dir) output_dir.mkdir(parents=True) # Change to repo root for imports to work correctly os.chdir(repo_root) # Generate documentation for each package for package, source_dir in PACKAGES.items(): print(f"Generating docs for {package} (from {source_dir})...") try: # Use pdoc3 to generate HTML documentation subprocess.run( [ "uv", "run", "pdoc3", "--html", "--output-dir", str(output_dir), "--force", package ], check=True, cwd=repo_root, ) except subprocess.CalledProcessError as e: print(f"Warning: Failed to generate docs for {package}, skipping...") print(f"Error: {e}") continue # Create index.html index_path = output_dir / "index.html" timestamp = datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S UTC") index_path.write_text(INDEX_HTML_TEMPLATE.format(timestamp=timestamp)) print("\nDocumentation generated successfully!") print(f"Open {output_dir}/index.html in your browser to view the documentation.") def main(): """Main entry point.""" # Determine paths script_dir = Path(__file__).parent.resolve() repo_root = script_dir.parent.parent # Default output directory output_dir = repo_root / "docs" / "python" # Allow override via command line argument if len(sys.argv) > 1: output_dir = Path(sys.argv[1]) generate_docs(output_dir, repo_root) if __name__ == "__main__": main()