lua-stub-generator

A Python CLI tool that generates Lua stub files from source code. Stub files contain the public interface — class definitions, field annotations, method signatures, enums, and global constants — with all implementation details stripped. This allows publishing API documentation for 3rd party developers without revealing proprietary source code.

Features

• Extracts classes (---@class), enums (---@enum), methods, and global constants
• Preserves all LuaDoc annotations (---@field, ---@param, ---@return, etc.)
• Replaces function bodies with empty stubs (end)
• Strips implementation details: SavegameUtil.* calls, InitializeClassReference(...), local functions, and copyright headers
• Preserves include(...) statements for correct dependency resolution
• Mirrors the input directory structure in the output
• By default only emits items tagged with ---@stub generate; use --all to include everything public
• Skips output file creation for files with no stub-worthy content

Requirements

• Python ≥ 3.12

Installation

pip install -e .

Or with uv:

uv pip install -e .

Usage

lua-stub-gen --output <dir> [--all] <input> [<input> ...]

Or equivalently:

python -m lua_stub_generator --output <dir> [--all] <input> [<input> ...]

Arguments

Argument	Short	Description
INPUT		One or more .lua files or directories (searched recursively)
--output DIR	-o	Output directory; input file tree structure is preserved
--all	-a	Include all public items, not just ---@stub generate tagged ones

Examples

Generate stubs for all tagged items in a directory:

lua-stub-gen -o stubs/ src/

Generate stubs for all public items (no filter):

lua-stub-gen --all -o stubs/ src/

Process a single file:

lua-stub-gen -o stubs/ src/RailVehicle/RailVehicle.lua

How it works

The tool uses a line-by-line state machine parser that recognises the following Lua constructs:

• ---@stub generate — marks a class or enum for inclusion in default mode
• ---@class Name : Parent — class definition with optional inheritance
• ---@enum Name — enum definition, body values are preserved
• function Cls:method(...) — method signature; body is replaced with end
• ClassName.FIELD = value — global constant assignment
• include("path") — always preserved

The output file is skipped entirely if it would contain no stub content.

Development

Install dev dependencies:

uv sync

Lint:

uv run ruff check lua_stub_generator/

Format:

uv run ruff format lua_stub_generator/