tealr_doc_gen

This tool is meant to be used together with tealr and is used to generate online documentation for lua/teal apis created with tealr

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:

{
  "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

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 tealrdoc_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 tealrdoc_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.