Moonwave Documentation Ecosystem

Moonwave is a command line tool designed to generate documentation from comments within Lua source code. It consists of three primary components:

• Moonwave Extractor: A Rust-based program that parses Lua files and extracts documentation into JSON format.
• Docusaurus Plugin: A React-based plugin for Docusaurus that visually renders the extracted JSON documentation.
• Moonwave CLI: A unified interface that abstracts the extractor and the Docusaurus plugin, allowing users to manage the entire documentation workflow without interacting with the underlying components directly.

In Moonwave, all documented entities (types, properties, or functions) must belong to a "class". A class is conceptually any Lua table containing fields or functions (e.g., a service, an OOP class, or a plain table). Each class generates its own dedicated API page.

You can define a class using either multi-line comments with an equals sign or single-line triple-dash comments. Both methods are equivalent.

--[=[
	@class MyFirstClass

	This is my first class.
]=]
local MyFirstClass = {}
MyFirstClass.__index = MyFirstClass

OR

--- @class MyFirstClass
---
--- This is my first class.
local MyFirstClass = {}
MyFirstClass.__index = MyFirstClass

Use @class <name> to denote a class. It is recommended to have one per .lua file.

For any doc comment that is not an @class (such as properties, functions, or types), you must include the @within <class name> tag to specify which class the item belongs to. Failing to include @within for non-class doc comments will result in an error.

--- @class MyClass
--- A sample class.
local MyClass = {}
MyClass.__index = MyClass

--- @prop name string
--- @within MyClass
--- A string referring to the name

Moonwave supports hierarchical organization for API documentation through nested sections. You can nest sections within [[classOrder.items]] to create a multi-level sidebar.

Nested sections inherit the ability to use classes, tag, and collapsed settings. You can control the collapsed state at any level of the hierarchy.

[[classOrder]]
section = "Parent Section"

[[classOrder.items]]
section = "Child Section 1"
classes = ["Class1", "Class2"]

[[classOrder.items]]
section = "Child Section 2"
tag = "childTag"

[[classOrder.items.items]]
section = "Grandchild Section"
classes = ["Class4", "Class5"]

Moonwave provides several features for Lua documentation workflows:

• Low Configuration: Generate a documentation website with minimal setup by using specific doc comments in your Lua code.
• Validation: Includes an extensive validation system to catch errors or inconsistencies in your documentation.
• JSON Output: Extracts documentation into JSON, making it compatible with various external tools.
• Readable Comment Format: Uses a simple doc comment format designed to be easily readable within the source code.

Generics are defined using angled brackets <>. While Moonwave generally follows the Luau Typechecking Guide, documentation types can be more flexible for clarity.

• Standard Generics: Use <T> to define a type variable: <T>(arg: T) -> (T, T).
• Type Variable Convention: Use single capital letters like T or U to indicate that two types must be the same. For example, (arg: T) -> T indicates that the return type is exactly the same as the input type, whereas (arg: any) -> any would allow the return type to differ from the input.
• Documentation Flexibility: Since docs are for reading, you can omit the declaration of <T> if it makes the type clearer, such as (arg: T) -> (T, T).

<T>(arg: T) -> (T, T)
() -> Promise<T>
(arg: T) -> T

If you prefer not to install Moonwave globally, you can use npx moonwave instead of the moonwave command. This will automatically download and run the latest version of Moonwave every time.

npx moonwave dev

Generate the static production content by running yarn build. The resulting static files will be located in the build directory and can be hosted on any static content hosting service.

$ yarn build

Start a local development server using yarn start. This command will automatically open a browser window and supports live reloading, meaning most changes to the site will be reflected immediately without a server restart.

$ yarn start

To host your website on a custom domain via GitHub Pages, you must provide a CNAME file. Create this file at the following path in your project:

yourProjectRoot/.moonwave/static/CNAME

Place your domain name inside this file.

You can build and publish your documentation website using the Moonwave CLI.

If you are using Git and GitHub Pages, you can build and publish in a single step:

moonwave build --publish

Otherwise, run moonwave build to generate the site locally. The output will be placed in a build directory in your project root. You can customize the output location using the --out-dir [path] flag.

Note: Add the build folder to your .gitignore to prevent committing build artifacts.

moonwave build --publish
# or
moonwave build --out-dir ./custom-build-path