How to generate API docs and use LSP?

[VorpalBlade]

I recently started looking at rune after dabbling a bit with rhai. I have to say the language itself looks nicer (especially the support for enums and pattern matching).

My use case is an advanced configuration language (I'm making something like ansible, or the NixOS system config. More specifically I'm making a version of this arch linux specific config manager (written in bash) that I can use on my work computer where I have to run Ubuntu). As such the speed of rhai would most likely be adequate, but rune looks like a nicer language to write in.

While the documentation for the Rune language itself is good, the documentation for embedding rune in a Rust program seems far more limited than for Rhai. As such there is a couple of operations that I would need that I haven't manage to figure out:

1. How to generate API docs for the native functions I expose? rhai has rhai-autodocs which works well. Rune has an empty module with no public API for me to use? It is clearly possible as https://rune-rs.github.io/docs/ exists. But I haven't manage to find any docs on how to do this.
2. There is apparently some sort of LSP support. That is nice, but how would one use it, to set it up with for example VS Code so that I can tab my own external types? Can't really find much about this.
3. Related to this is other dev tooling (this is quite lacking for rhai, syntax highlighting for vscode seems to be all there is). What exists for rune? Is there (or are there plans for) a runefmt for example?

[udoprog]

Hi!

So the way you use the tooling is to construct a modular commandline where you install your custom modules.

That gives you 1, once you have the modular comamndline, generating documentation will include your custom modules. It also gives you 2, you can run the language server by using your modular commandline entry cargo run -p my-commandline-crate -- languageserver. The blog post covers how you can configure this in an editor. I think 3 follows naturally from this. The tooling available is the vscode extension and the commandline which you can configure.

Hope this helps!

[VorpalBlade]

Ah, so I need an extra binary for this. Not something that can be part of my main binary? That is slightly unfortunate as I like being able to download a single binary and get everything (I integrate clap_mangen and clap_completions as sub-commands normally, so the binary itself can produce any extra files). I already have a clap based cli, so unless I can somehow attach this under a sub-command there it is slightly unfortunate.

[udoprog]

I would like to see this documentation ported to the book, if that's something you're interested in doing while navigating this I'd love to help you out.

[VorpalBlade]

I'm unreliable when it comes to making contributions as well as working on my own code, so I can't promise anything.

But I think perhaps splitting the book into multiple sections (headings in the SUMMARY.md for the mdbook iirc) might be a good option. Rhai has this mostly figured out in their book. (Serious kudos to them, that must have taken a ton of effort!)

For rune I would basically:

• Move most of what is currently there to a "Users guide" section. Leave foreword and introduction outside at the start.
• Start a new section called "Rust integration".
  • "Advanced" seems to fit as a sub section to it.
  • As does "External Types" arguably. It is more about the integration than user guide.
• Move things that are spread out elsewhere (such as this blog I didn't know existed) into the appropriate section there.

Doesn't have to (and won't) be perfect to begin with. But hopefully future changes will move towards such a structure.