<div align="center">
# 📚 EmmyLua Doc CLI
[](https://crates.io/crates/emmylua_doc_cli)
[](../../LICENSE)
</div>
`emmylua_doc_cli` is a powerful command-line tool for generating documentation directly from your Lua source code and EmmyLua annotations. Built with Rust, it offers exceptional performance and is a core component of the `emmylua-analyzer-rust` ecosystem.
---
## ✨ Features
- **🚀 Blazing Fast**: Leverages Rust's performance to parse and generate documentation for large codebases in seconds.
- **✍️ Rich Annotation Support**: Intelligently interprets EmmyLua annotations (`---@class`, `---@field`, `---@param`, etc.) to generate detailed and accurate documentation.
- **🔧 Highly Customizable**:
- Override the default templates with `--override-template` to match your project's branding.
- Inject custom content into the main page using the `--mixin` option to add guides, tutorials, or other static pages.
- **📦 Multiple Output Formats**: Generate documentation in **Markdown** or **JSON** for maximum flexibility.
- **🤝 CI/CD Ready**: Automate your documentation publishing workflow with seamless integration into services like GitHub Actions.
---
## 📦 Installation
Install `emmylua_doc_cli` via cargo:
```shell
cargo install emmylua_doc_cli
```
Alternatively, you can grab pre-built binaries from the [**GitHub Releases**](https://github.com/EmmyLua/emmylua-analyzer-rust/releases) page.
---
## 🚀 Usage
### Basic Usage
Generate documentation for all Lua files in the `src` directory and output to the default `./docs` folder:
```shell
emmylua_doc_cli ./src -o ./docs
```
### Advanced Usage
#### Generate JSON Output
Output the documentation structure as a JSON file for custom processing:
```shell
emmylua_doc_cli . -f json -o ./api.json
```
#### Customize Site Name
Set a custom name for the generated documentation site:
```shell
emmylua_doc_cli . -o ./docs --site-name "My Awesome Project"
```
#### Ignore Files
Exclude certain directories or files from the documentation:
```shell
emmylua_doc_cli . -o ./docs --ignore "third_party/**,test/**"
```
---
## 🛠️ CI/CD Integration
Automate the process of building and deploying your documentation to GitHub Pages using GitHub Actions.
**Example `.github/workflows/docs.yml`:**
```yaml
name: Generate and Deploy Docs
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Install emmylua_doc_cli
run: cargo install emmylua_doc_cli
- name: Generate Docs
run: emmylua_doc_cli ./src -o ./docs --site-name "My Project"
```
---
## Command Line Options
```
Usage: emmylua_doc_cli [OPTIONS] [WORKSPACE]...
Arguments:
[WORKSPACE]... Path to the workspace directory
Options:
-c, --config <CONFIG> Configuration file paths. If not provided, both ".emmyrc.json" and ".luarc.json" will be searched in the workspace directory
--include <INCLUDE> Comma separated list of include patterns. Patterns must follow glob syntax. It will override the default include patterns.
--ignore <EXCLUDE> Comma separated list of exclude patterns. Patterns must follow glob syntax(deprecated, use --exclude instead)
--exclude <EXCLUDE> Comma separated list of exclude patterns. Patterns must follow glob syntax. Exclude patterns take precedence over include patterns
-f, --output-format <OUTPUT_FORMAT> Specify output format [default: markdown] [possible values: json, markdown]
-o, --output <OUTPUT> Specify output destination (can be stdout when output_format is json) [default: ./output]
--override-template <OVERRIDE_TEMPLATE> The path of the override template
--site-name <SITE_NAME> [default: Docs]
--mixin <MIXIN> The path of the mixin md file
--verbose Verbose output
-h, --help Print help
-V, --version Print version
```