Lua Documentation Generator

specialised for Hades 2 modding

This project is a work in progress!

This project is intended to be easy to adapt for other lua environments by way of forking, but it is not built to handle multiple lua environments at once.

Usage

The plan is that this tool:

• defines an intermediate representation (IR) stored as JSON files, defined by its schema (luadocgen/schema).
• allows for merging IR files to aggregate information from these various sources and multiple users.
• contains converters from data sources to IR (luadocgen/converters_from).
• contains converters from IR to documentation formats (luadocgen/converters_into).

Additionally, the IR can be manually edited, or fragments can be manually written and merged in.

Usage: python -m luadocgen will show sub-command options:

• join(2): merge all .json IR files in a directory and output the merged .json IR to a destination directory
• from(3): invoke a converter (from converters_from) on an inputs directory for data sources and an outputs directory for IR files.
• into(3): invoke a converter (from converters_into) on an inputs directory for IR files and an outputs directory for documentation files.

Converters

From

• luascript_exec: Executes game scripts and recursively imports them into a lua environment inside of python, because it's easier than doing static analysis at the moment.
• luascript: (PLANNED) Actually statically analyses the game scripts properly.
• runtime: (PLANNED) To get coverage information on the lua environment, we can run logging tools within the game, whatever format this is logged to can be consumed by this to include in the documentation.
• often in lua environments, the engine the lua is embedded into defines stuff outside of the scripts, these may need to be manually documented or dumped in some way, and then a converter can be made if needed to merge into a common IR.

Into

• luacats: Produces LuaCATS annotations (for sumneko lua language server in VS code) that are all namespaced, which would be labourious to do manually.
• docusaurus: (PLANNED) Produces (or patches within a marked region) markdown files suitable for Docusaurus wiki.

Schema

The IR is essentially a list of Definition, which can be specialised, but at least store:

• Formatted description and usage examples (as markdown, which can be displayed by VS Code and Docusaurus).
• Information on where the definition was sourced from, as a list of Origin which may store many different things.
• If a human has verified this definition (could be changed to a game version or timestamp, or its own Origin?).

Without an Origin, a Definition is merely an abstract thing, this allows it to be flexible enough to describe very odd lua environments.
Some definitions will correspond to specific values or singletons, others will correspond to templates or structures.

For an exact breakdown of the schema, look into the source code (luadocgen/schema).

Examples

Some kinds of Origin:

• FileOrigin: The location in a script file (e.g. line number) where the definition can be found.
• GlobalOrigin: Indicates that this definition is in the global scope (e.g. converters_into/luacats uses this to determine the global environment).

Some kinds of Definition:

• FunctionDefinition: A function has typed parameters and typed return values.
• TableDefinition: A table can represent many things in lua, so this definition contains many parts (non-exhaustive):
  • A table can act like an array or map, having a single type for its keys and a single type for its values.
  • A table can act like a namespace, having a different value type for each individual key.
  • A table can have a metatable which may make it have special operators or inherit structure.

Definition Remapping

In order to merge definitions between IR generated from partial sources, they need to be stored against unique and stable keys.
Since definitions are abstract, the keys used to store the definitions in the IR are not necessarily based on anything in particular, as long as we choose ones that are stable and unique.
Since IR generated from different sources might have different information available to decide the keys for definitions, there may be multiple records for the same actual definition.
So we need to a way to identify multiple definitions as one, or we may want to rename them over time without needing to notify every contributor.
For this purpose the IR has a field for remapping the keys of definitions.

Technical

The versions of packages in requirements.txt are not exact, currently it can work with python 3.12 to 3.14.

This project is intended to be linted by pylance in VS Code, using 'standard' strictness.
Currently only one file produces errors under these settings, luadocgen/converters_from/luascript_exec.py due to imperfect typing provided for luaparser and lupa.