114 lines
6.3 KiB
Markdown
114 lines
6.3 KiB
Markdown
Rhai Script Documentation Tool
|
|
==============================
|
|
|
|
{{#include ../links.md}}
|
|
|
|
|
|
The Rhai Script Documentation Tool, `rhai-doc`, takes a source directory and scans for
|
|
Rhai script files (recursively), building a web-based documentation site for all [functions] defined.
|
|
|
|
Documentation is taken from [MarkDown]-formatted [doc-comments] on the [functions].
|
|
|
|
|
|
Author: [`@semirix`](https://github.com/semirix)
|
|
|
|
Repo: [on GitHub](https://github.com/rhaiscript/rhai-doc)
|
|
|
|
Binary: [on `crates.io`](https://crates.io/crates/rhai-doc)
|
|
|
|
Example: [on `rhai.rs`](https://rhai.rs/rhai-doc)
|
|
|
|
|
|
Install
|
|
-------
|
|
|
|
```sh
|
|
cargo install rhai-doc
|
|
```
|
|
|
|
|
|
Flags and Options
|
|
-----------------
|
|
|
|
| Flag/Option | Parameter | Default | Description |
|
|
| ----------------- | :-------------: | :---------------: | -------------------------------------------------------------------------------------- |
|
|
| `-h`, `--help` | | | print help |
|
|
| `-V`, `--version` | | | print version |
|
|
| `-a`, `--all` | | | generate documentation for all functions, including [`private`] ones _(default false)_ |
|
|
| `-v` | | | use multiple to set verbosity: 1=silent, 2,3 _(default)_=full |
|
|
| `-c`, `--config` | _\<file\>_ | `rhai.toml` | set configuration file |
|
|
| `-D`, `--dest` | _\<directory\>_ | `dist` | set destination directory for documentation output |
|
|
| `-d`, `--dir` | _\<directory\>_ | current directory | set source directory for Rhai scripts |
|
|
| `-p`, `--pages` | _\<directory\>_ | `pages` | set source directory for additional [MarkDown] page files to include |
|
|
|
|
|
|
Commands
|
|
--------
|
|
|
|
| Command | Description | Example |
|
|
| ------- | ----------------------------------------------------- | -------------- |
|
|
| _none_ | generate documentation | `rhai-doc` |
|
|
| `new` | create a skeleton `rhai.toml` in the source directory | `rhai-doc new` |
|
|
|
|
|
|
Configuration file
|
|
------------------
|
|
|
|
A configuration file, which is usually named `rhai.toml`, contains configuration options for
|
|
`rhai-doc` and must be placed in the source directory.
|
|
|
|
A skeleton `rhai.toml` can be generated inside the source directory via the `new` command.
|
|
|
|
An alternate configuration file can be specified via the `--config` option.
|
|
|
|
### Example
|
|
|
|
```toml
|
|
name = "My Rhai Project" # project name
|
|
color = [246, 119, 2] # theme color
|
|
root = "/docs/" # root URL for generated site
|
|
index = "home.md" # this file becomes 'index.html'
|
|
icon = "logo.svg" # project icon
|
|
stylesheet = "my_stylesheet.css" # custom stylesheet
|
|
code_theme = "atom-one-light" # 'highlight.js' theme
|
|
code_lang = "ts" # default language for code blocks
|
|
extension = "rhai" # script extension
|
|
google_analytics = "G-ABCDEF1234" # Google Analytics ID
|
|
|
|
[[links]] # external link for 'Blog'
|
|
name = "Blog"
|
|
link = "https://example.com/blog"
|
|
|
|
[[links]] # external link for 'Tools'
|
|
name = "Tools"
|
|
link = "https://example.com/tools"
|
|
```
|
|
|
|
Configuration Options
|
|
---------------------
|
|
|
|
| Option | Value type | Default | Description |
|
|
| ------------------ | ------------------------ | :-------------: | --------------------------------------------------------------------------------------- |
|
|
| `name` | string | _none_ | name of project – used as titles on documentation pages |
|
|
| `color` | RGB values (0-255) array | `[246, 119, 2]` | theme color for generated documentation |
|
|
| `root` | URL string | _none_ | root URL generated as part of documentation |
|
|
| `index` | file path | _none_ | main [MarkDown] file – becomes `index.html` |
|
|
| `icon` | file path | Rhai icon | project icon |
|
|
| `stylesheet` | file path | _none_ | custom stylesheet |
|
|
| `code_theme` | theme string | `default` | [`highlight.js`](https://highlightjs.org/) theme for syntax highlighting in code blocks |
|
|
| `code_lang` | language string | `ts` | default language for code blocks |
|
|
| `extension` | extension string | `.rhai` | script files extension (default `.rhai`) |
|
|
| `google_analytics` | ID string | _none_ | [Google Analytics](https://analytics.google.com) ID |
|
|
| `[[links]]` | table | _none_ | external links |
|
|
| • `name` | string | _none_ | • title of external link |
|
|
| • `link` | URL string | _none_ | • URL of external link |
|
|
|
|
|
|
~~~admonish abstract.small "MarkDown pages"
|
|
|
|
By default, `rhai-doc` will generate documentation pages from a `pages` sub-directory
|
|
under the scripts directory. The pages are assumed to be in [MarkDown].
|
|
|
|
Alternatively, you can specify another location via the `--pages` option.
|
|
~~~
|