Skip to content

Commit 16bcc62

Browse files
CppCXYCppCXY
committed
update readme
1 parent d910f4f commit 16bcc62

File tree

3 files changed

+113
-14
lines changed

3 files changed

+113
-14
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ Download the latest binaries from our [releases page](https://github.com/CppCXY/
207207
<summary><b>🔧 Build from Source</b></summary>
208208

209209
```bash
210-
git clone https://github.com/CppCXY/emmylua-analyzer-rust.git
210+
git clone https://github.com/EmmyLuaLs/emmylua-analyzer-rust.git
211211
cd emmylua-analyzer-rust
212212
cargo build --release -p emmylua_ls
213213
```
@@ -315,7 +315,7 @@ emmylua_check ./src --verbose --format json
315315

316316
```bash
317317
# Clone the repository
318-
git clone https://github.com/CppCXY/emmylua-analyzer-rust.git
318+
git clone https://github.com/EmmyLuaLs/emmylua-analyzer-rust.git
319319
cd emmylua-analyzer-rust
320320

321321
# Build all crates

‎crates/emmylua_check/README.md

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -73,13 +73,6 @@ Output diagnostics in JSON format to a file for further processing:
7373
emmylua_check . -f json --output ./diag.json
7474
```
7575

76-
#### Treat Warnings as Errors
77-
78-
In CI environments, this is a useful option to enforce fixing all warnings:
79-
```shell
80-
emmylua_check .
81-
```
82-
8376
---
8477

8578
## ⚙️ Configuration

‎crates/emmylua_doc_cli/README.md

Lines changed: 111 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,121 @@
1-
# EmmyLua Doc Cli
1+
<div align="center">
22

3-
This is a command line tool for generating EmmyLua doc from Lua source code.
3+
# 📚 EmmyLua Doc CLI
44

5-
## Installation
5+
[![Crates.io](https://img.shields.io/crates/v/emmylua_doc_cli.svg?style=for-the-badge&logo=rust)](https://crates.io/crates/emmylua_doc_cli)
6+
[![GitHub license](https://img.shields.io/github/license/CppCXY/emmylua-analyzer-rust?style=for-the-badge&logo=mit&color=blue)](../../LICENSE)
67

8+
</div>
9+
10+
`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.
11+
12+
---
13+
14+
## ✨ Features
15+
16+
- **🚀 Blazing Fast**: Leverages Rust's performance to parse and generate documentation for large codebases in seconds.
17+
- **✍️ Rich Annotation Support**: Intelligently interprets EmmyLua annotations (`---@class`, `---@field`, `---@param`, etc.) to generate detailed and accurate documentation.
18+
- **🔧 Highly Customizable**:
19+
- Override the default templates with `--override-template` to match your project's branding.
20+
- Inject custom content into the main page using the `--mixin` option to add guides, tutorials, or other static pages.
21+
- **📦 Multiple Output Formats**: Generate documentation in **Markdown** or **JSON** for maximum flexibility.
22+
- **🤝 CI/CD Ready**: Automate your documentation publishing workflow with seamless integration into services like GitHub Actions.
23+
24+
---
25+
26+
## 📦 Installation
27+
28+
Install `emmylua_doc_cli` via cargo:
729
```shell
830
cargo install emmylua_doc_cli
931
```
32+
Alternatively, you can grab pre-built binaries from the [**GitHub Releases**](https://github.com/EmmyLua/emmylua-analyzer-rust/releases) page.
33+
34+
---
35+
36+
## 🚀 Usage
37+
38+
### Basic Usage
39+
40+
Generate documentation for all Lua files in the `src` directory and output to the default `./docs` folder:
41+
```shell
42+
emmylua_doc_cli ./src -o ./docs
43+
```
44+
45+
### Advanced Usage
46+
47+
#### Generate JSON Output
48+
49+
Output the documentation structure as a JSON file for custom processing:
50+
```shell
51+
emmylua_doc_cli . -f json -o ./api.json
52+
```
1053

11-
## Usage
54+
#### Customize Site Name
1255

56+
Set a custom name for the generated documentation site:
1357
```shell
14-
emmylua_doc_cli ./tests/lua --output ./tests/doc
58+
emmylua_doc_cli . -o ./docs --site-name "My Awesome Project"
59+
```
60+
61+
#### Ignore Files
62+
63+
Exclude certain directories or files from the documentation:
64+
```shell
65+
emmylua_doc_cli . -o ./docs --ignore "third_party/**,test/**"
66+
```
67+
68+
---
69+
70+
## 🛠️ CI/CD Integration
71+
72+
Automate the process of building and deploying your documentation to GitHub Pages using GitHub Actions.
73+
74+
**Example `.github/workflows/docs.yml`:**
75+
```yaml
76+
name: Generate and Deploy Docs
77+
78+
on:
79+
push:
80+
branches:
81+
- main
82+
83+
jobs:
84+
build:
85+
runs-on: ubuntu-latest
86+
steps:
87+
- name: Checkout
88+
uses: actions/checkout@v4
89+
90+
- name: Install Rust toolchain
91+
uses: dtolnay/rust-toolchain@stable
92+
93+
- name: Install emmylua_doc_cli
94+
run: cargo install emmylua_doc_cli
95+
96+
- name: Generate Docs
97+
run: emmylua_doc_cli ./src -o ./docs --site-name "My Project"
98+
```
99+
100+
---
101+
102+
## Command Line Options
103+
104+
```
105+
Usage: emmylua_doc_cli [OPTIONS] [WORKSPACE]...
106+
107+
Arguments:
108+
[WORKSPACE]... Path to the workspace directory
109+
110+
Options:
111+
-c, --config <CONFIG> Configuration file paths. If not provided, both ".emmyrc.json" and ".luarc.json" will be searched in the workspace directory
112+
--ignore <IGNORE> Comma separated list of ignore patterns. Patterns must follow glob syntax
113+
-f, --output-format <OUTPUT_FORMAT> Specify output format [default: markdown] [possible values: json, markdown]
114+
-o, --output <OUTPUT> Specify output destination (can be stdout when output_format is json) [default: ./output]
115+
--override-template <OVERRIDE_TEMPLATE> The path of the override template
116+
--site-name <SITE_NAME> [default: Docs]
117+
--mixin <MIXIN> The path of the mixin md file
118+
--verbose Verbose output
119+
-h, --help Print help
120+
-V, --version Print version
15121
```

0 commit comments

Comments
 (0)