merge documentation from rustdocs json output

[coderedart]

TLDR;
Tealr is mostly going to be used to wrap Rust libraries (either to use from lua or to document the plugin APIs of rust apps who embed lua). Rust libraries already have god tier documentation, so embedding or linking to that documentation by the tealr types will be really useful.

I use the same names for the tealr functions which are wrapping rust fns. just like i can do methods.add_document("whatever"), if i could just annotate the next item's rust equivalent like methods.add_rust_name(Some("rust fn name")), tealr could use export that info when it generates the json. then, it can simply take the rustdoc's exported json for the relevant crates and add it as additional documentation to the tealr docs. rustdoc can output the parsed documentation from the crate source as json (though its nightly and not stable yet).

https://coderedart.github.io/luaegui/ I am working on completing the bindings for egui and there's a LOT of very simple functions. an example is Response::clicked() on tealr side https://coderedart.github.io/luaegui/Response.html#clicked and https://docs.rs/egui/latest/egui/struct.Response.html#method.clicked on rust side. i feel really frustrated just thinking about how i need to copy / paste all these docs. so, i decided that i will just document the types and very important functions (or functions that are significantly different from rust versions) and tell people to just use the docs.rs for the actual detailed documentation as most types / functions have same names. I can just add a docs.rs link to the types too, for easier access.

I don't really have a concrete vision of how this would work. but, better to put this here, before i forget it. and to keep in mind this idea while evolving the design of tealr_doc_gen, so that it won't be hard IF this feature is implemented in the future.

references:
rustdoc json tracking issue : rust-lang/rust#76578
rfc : https://rust-lang.github.io/rfcs/2963-rustdoc-json.html

[lenscas]

Correct me if I am wrong, but the json output is not yet stable. I don't know how I feel about having tealr_doc_gen dependant on a nightly feature, especially considering it is yet another file that users need to generate before tealr_doc_gen can work.

Having said that, I am slowly working on allowing users to create custom templates and the like. It should be possible to also allow people to hook into the markdown parser, allowing them to create it themselves.

Then later it is possible to add functions to help with this while never forcing people to generate this rust doc json if they don't want to. It also means that changes in the format will force users to update tealr_doc_gen. As the code used to do this link is under their own control.

[coderedart]

we cannot have this yet.

but, better to put this here, before i forget it. and to keep in mind this idea while evolving the design of tealr_doc_gen, so that it won't be hard IF this feature is implemented in the future.

the templates features sounds even better. anything that avoids raw copy pasting docs from rust -> tealr.

[lenscas]

#9 adds a MVP version of custom templates. It basically only misses a way to alter the generated html from the markdown in the docs.

[lenscas]

With the release of v0.3.0-alpha1 of tealr_doc_gen you can now create custom templates (.etlua files) and a custom "runner" lua script that is normally used to load etlua and run the template. You should be able to parse rustdoc's json from either of those scripts and go from there.

Only downside is that there is no way to store custom state between between pages, which means that the rustdoc json will have to be parsed for every page that gets generated.

In addition, the latest version of tealr has an update to its FromToLua macro, so now it is aware of existing doc comments for fields and the type it runs on itself.