Auto-generate Lua API documentation #1998
Conversation
|
For now I assume a single version rebuilt from a branch HEAD will be fine. At the moment the docs are pretty spotty. Whet it gets to the point of being generally useful we would probably want to host versions matching SILE releases. The same will be true of manuals and Rust API docs. This probably means getting the Nix Flake setup with an option to generate docs, then using that from the website repo build script to generate the docs for desired branches and tags as part of the static site build. |
alerque
force-pushed
the
ldoc
branch
5 times, most recently
from
a7fc89a
to
40d667a
Compare
|
The issue of versioning (and hence stable URS) is not addressed yet, but the Lua API docs are being posted on the SILE website: https://sile-typesetter.org/lua-api/. Definitely not complete but, enough that even I've learned some about SILE internals from reading them! I'm probably going to merge this soon because this needs to be added to and tweaked as the main develop branch, not off here on its own. |
|
(Rebuilds currently happen running the website repo CI, not the CI for this repo. I'm looking into how to setup a rebuild hook so the website updates any time the development branch does.) |
| ---@return table|nil AST command node | ||
| -- looking only at the first level. | ||
| -- (We're not reimplementing XPath here.) | ||
| -- @tparam table tree AST tree |
There was a problem hiding this comment.
@Omikhleia I think I recall you saying the type hinds you added here worked in VSCode. I can't find the discussion but I have a memory of saying we probably wanted to use LDoc format in the future but that something was better than nothing to start with. This PR adds LDoc support and hence I tweaked these with type hints for that system. That being said it would be nice to figure out what else these can be used for and if we can figure out a way they work for everybody. Were you using these for an LSP or something? If so which one? And does this format work too? Or do we need to figure out how to adapt the type hints in a way that work for multiple systems?
There was a problem hiding this comment.
LDoc has quite a few ways of handing tags. Before I get too fancy with them I want to know if they are going to be used for anything other that ldoc.
For example @tparam string var defines a parameter of type string named var, but it also has \string var as an alias for the same thing. We can also setup custom types, which I want to do so we can have @tparam measurement width or @tparam ast tree for example that are linked to SILE.types.measurement and SILE.types.ast (or whatever that ends up going, right now it's just a table).
There was a problem hiding this comment.
@alerque There are a bunch of LSP and VSCode add-ons for Lua. I currently use https://github.com/Tencent/LuaHelper -- I can't remember why I picked that one... I also tried https://luals.github.io/ at one point (installed on my main host, but disabled).
Both have helpers to generate the documentation from code, and a fairly similar syntax for parameters, with @param name type description -- in line with my plugins for other languages (Typescript, Python...), mimicking their conventions for optional parameters and variant types (e.g. table? and/or table|nil etc.)
I am afraid LDoc's @tparam is quite specific to it, and doesn't have much support elsewhere... Likewise, marking optional params with[opt] seems unusual (AFAIK)
It's annoying people keep reinventing the wheel there, with their own language documentation things.
I am not going to type those manually if I can avoid :) Hopefully, Copilot can help here too, though I don't always have it on (esp. in vacations, with a low/limited bandwidth).
There was a problem hiding this comment.
Addition: It seems both plugins I mentioned use EmmyLua annotations (or a variant?).
There was a problem hiding this comment.
🤦 🤦 🤦
EmmyLua looks like a disaster to me, but the luals (formerly Sumneko Lua) stuff looks promising. They are not the same but both allow some customization and it might be possible to map out a dual-purpose ground that has some meaning to both.
Catches any new dependencies introduced in these late running code locations.
Closes #1337
Still need to think of a place to host this.