Rhai documentation generation

[schungx]

Hi, I see your comment on "Rhai currently does not have any utilities existing for generating documentation (for the rust provided API), once something comes out we'll include it."

May I point you to the metadata feature which provides metadata (including comments) on Rust/Rhai functions: https://rhai.rs/book/engine/metadata/index.html

[makspll]

Hi @schungx!

Function metadata is definitely very useful, however when it comes to documentation I am very much looking for a parallel to tealr, Specifically the TypeWalker -> definition file -> documentation pipeline.

It would be amazing if rhai also had vscode supported static typing via such definition files, since then it would parallel the functionality available via mlua + tealr.

I know @lenscas is working on extending tealr's functionality to apply to more than just teal definition files, so once that's complete, this could maybe be applied to rhai!

[lenscas]

@makspll though it will be possible for people to create their own template for type definitions (and documentation pages), keep in mind that for the foreseeable future tealr's way of storing type information very much mimics teal's syntax. That means that in order to do this you would basically need to write a parser to go from teal to rhai.

It also means that some type information is lost because teal doesn't (yet) supports it. For example Option is marked the same as T.

I would love to change this to something more generic but that is such a big change that I won't be able to make it myself for a long time.

[makspll]

Ah, thanks for chiming in!
Well it's probably best to roll a custom solution for rhai,

Or help make tealr more generic with contributions.

[schungx]

There is https://github.com/rhaiscript/lsp which is in the works... it uses a Rhai-based definition file format to document functions, but still under development at this point and very raw. There is no typing support yet.

I understand your point now.

[makspll]

Oh this is fantastic to see, I will be keeping an eye on that project

[schungx]

However, without much knowledge of Teal, but from a general overall read of the tealr README, it seems to auto-gen documentation based on actual functions code (and comments), then format said documentation into a nice view.

Rhai can do that currently, via:

Register function -> capture metadata as JSON -> format JSON with template engine -> web pages

The LSP in the future will load this JSON and provide function docs.

Unless I'm mistaken about tealr, what it provides is already available for Rhai.

Also, there is rhai-doc that auto-generates a documentation site based on a directory of Rhai script files. Example here: https://rhai.rs/rhai-doc/

[makspll]

Yes it is possible to use what's already available in rhai to generate documentation,

It's just this templating step is not something I am interested in developing at this moment (writing an interface for bevy in multiple languages is alot of work), hence why I am looking for a more opinionated out-of-the box solution.

rhai-doc is great, but it works the other way round to what I'd like, I want to document the API available to scripts not the other way round.

Hope this makes sense.

[schungx]

Ah. Understood now. Makes sense!

I like OOTB solutions also!

rhai-doc is great, but it works the other way round to what I'd like, I want to document the API available to scripts not the other way round.

In fact, I hear you. Unfortunately rhai-doc was written with some restrictions. I tried making it native + script, but it wasn't easy. In the end I abandoned the attempt.

It is way simpler to use something like handlebars or tera and load the def JSON to generate a standard site. This is something that I've been thinking of writing, but haven't yet (since there hasn't been any demand). Maybe this will give me a reason to write it!

[makspll]

That's fair!

I think another reason I don't want to roll a custom solution, is that the way documentation should look would likely end up an endless bike-shedding issue. If the Rhai project itself declares a style however, then I feel people will be much more likely to accept it haha. Making docs customizable is also a whole other problem, and the whole thing definitely deserves its own crate.

It's interesting that there's not been demand, I think in this case documentation of this sort is very very important, and not just for external users and modders, but for the developer themselves since making a moddable game means writing a mod for your own game!