# tealr_doc_gen
This tool is meant to be used together with [tealr](https://github.com/lenscas/tealr) and is used to generate online documentation for lua/teal apis created with [tealr](https://github.com/lenscas/tealr/tree)
## Rendered Example
https://lenscas.github.io/tealsql/
## Features:
- full markdown support
- code highlighting in code examples
- multiple theme support
- snippets marked as `teal_lua` get compiled to `lua` and both versions get embedded.
- When compiling `teal_lua` snippets, any errors get logged.
# Install
To install, simply run
```
cargo install tealr_doc_gen
```
Cargo will do the rest.
# Running
To create the documentation, `tealr_doc_gen` needs a couple of things.
## Config file
First: A config file. To generate a basic one you can run `tealr_doc_gen gen-self --config`
This will create a new file in the current directory named `tealr_doc_gen_config.json`. You can also pass the `--print` flag as well to make tealr_doc_gen print the config file rather than creating the file.
Alternatively, you can grab a basic config file from below:
```json
{
"doc_template": "Builtin",
"is_global": false,
"page_root": "",
"store_in": "pages",
"name": "NAME_OF_YOUR_PROJECT",
"type_def_files": {
"runner": "Builtin",
"templates": {
"teal": {
"extension": ".d.tl",
"template": "Teal"
}
}
},
"lua_addon": {
"words": [],
"files": [],
"settings": {}
}
}
```
Change `NAME_OF_YOUR_LIBRARY` to the name of your project. This will have an effect on the name of the definition files.As well as the `name` value in the `plugin.json` file of the lua language server addon.
Other notable options:
`is_global`: Decides if the project is directly accessible in the global scope or if it is something that has be loaded into the lua vm like a library. Basically, set it to false if you are making a library and to true if you are embedding lua into your project.
`store_in`: What folder to store the documentation in.
`page_root`: If you put the documentation online but it is in a sub folder like `https://lenscas.github.io/tealsql/` rather than at the root then you want to put the path needed to access it here. In the tealsql example,that would be `tealsql`
`lua_addon`: The values here are copied into the `plugin.json` file.
`doc_template` and `type_def_files` are for advanced customization. Only if you want to alter the generated html or similar will you need to change these values.
## Json file with definitions
The second thing you need is a json file containing the description of your API. This can easily be generated by tealr as shown below:
Simply add all the types you want to have documented through calls to `process_type`, call `to_json()` and save the result to a file.
`tealr_doc_gen` searches for a json file with the same name as the `name` value in its config. Example, say you have `tealsql` in the `name` field then it looks for a file named `tealsql.json`
```rs
use tealr::{
TypeWalker,
};
fn main() {
let types = TypeWalker::new()
.process_type::<crate::TypeYouWantToDocument>()
.process_type<crate::OtherTypeYouWantToDocument>();
let json = types.to_json().unwrap();
println!("{}",json); //either print and copy/paste manually or save directly to a file
}
```
## Running it
Once you have the json file and the configuration set up, run `tealr_doc_gen run` to create the documentation.
When running tealr*doc_gen does some checks on the exported definitions. If these checks fail it will \_not* stop generating _but_ it likely means that the generated documentation contains broken links, example code that fails to compile, etc.
As such it is recommended to fix the definition file and run tealr*doc_gen again when these happen. You should \_not* have to alter the definition file by hand, rather fix the example documentation, links in documentation and/or add any missing types to the type walker and then generate the definition json again.