mq-docs 0.1.4

Documentation generator for mq functions and macros
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

<h1 align="center">mq-docs</h1>

A documentation generator for [mq](https://github.com/harehare/mq) functions, macros, and selectors. Generates reference documentation from built-in definitions or custom `.mq` files in multiple output formats.

![mq-docs](./assets/mq-docs.jpg)

## Features

- Generates documentation for functions, macros, and selectors
- Multiple output formats: Markdown, plain text, and HTML
- HTML output includes interactive sidebar navigation, search/filter, and responsive design
- Supports built-in modules, custom files, and loadable modules (e.g., `csv`, `json`)
- Available as both a CLI tool and a library

## Installation

### Using the Installation Script (Recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/harehare/mq-docs/main/bin/install.sh | bash
```

The installer will:
- Download the latest release for your platform
- Verify the binary with SHA256 checksum
- Install to `~/.mq-check/bin/`
- Update your shell profile (bash, zsh, or fish)

After installation, restart your terminal or run:
```bash
source ~/.bashrc  # or ~/.zshrc, or ~/.config/fish/config.fish
```

### Cargo

```bash
# Install from crates.io
cargo install mq-docs
# Install using binstall
cargo binstall mq-docs@0.1.0
```

### From Source

```bash
git clone https://github.com/harehare/mq-docs.git
cd mq-docs
cargo build --release
# Binary will be at target/release/mq-docs
```

## Usage

### CLI

```bash
# Generate documentation for built-in functions (default: Markdown)
mq-docs

# Generate from custom files
mq-docs file1.mq file2.mq

# Load specific modules
mq-docs -M csv -M json

# Include built-in functions alongside custom modules/files
mq-docs -B -M json file.mq

# Specify output format
mq-docs -F html > docs.html
mq-docs -F markdown > docs.md
mq-docs -F text
```

#### Options

| Option                      | Description                                                        |
| --------------------------- | ------------------------------------------------------------------ |
| `[FILES]`                   | Input `.mq` files to generate documentation from                   |
| `-M, --module-names <NAME>` | Module names to load (repeatable)                                  |
| `-F, --format <FORMAT>`     | Output format: `markdown`, `text`, or `html` (default: `markdown`) |
| `-B, --include-builtin`     | Include built-in functions alongside modules/files                 |

### Library

```rust
use mq_docs::{generate_docs, DocFormat};

fn main() -> miette::Result<()> {
    // Generate Markdown documentation for built-in functions
    let docs = generate_docs(&None, &None, &DocFormat::Markdown, false)?;
    println!("{docs}");
    Ok(())
}
```

## Output Formats

- **Markdown** - Tables suitable for rendering in documentation sites or GitHub
- **Text** - Plain text output for terminal viewing
- **HTML** - Self-contained single-page HTML with dark theme, sidebar navigation, search filtering, and mobile support

## License

MIT