Generate DOC.md from annotations

[L3MON4D3]

Some preliminary progress to unifying annotations and information living currently in DOC.md.
This uses luals-mdgen to read code for rendering markdown from lua-codeblocks.

This PR will implement the framework and add annotation for the functions implemented in lua/luasnip/init.lua, and maybe one or two of the snippet-constructor functions so that there is a good idea on whether this is feasible for the entire documentation :D

[bew]

Glad to see this 🤩
I did a first pass on it, only oooking at the Nix stuff & type annotations for now, I'll check out the template & ci later on I think.

Is it at any kind of ready state ?
Or what are you tweaking / what is still missing ?

[L3MON4D3]

Hey, thanks for taking a look :)

I have one or two small things (rename some fields in luals-mdgen), but otherwise I'll not add anything else.
Feel free to put your stamp of approval on the changes :P

[bew]

Re-reading parts of this PR, I missed a few files during my last set of indent changes 👀 They can be done later though.
You'll have to regen de final DOC.md (I didn't play with that) I think before merging.

[L3MON4D3]

Re-reading parts of this PR, I missed a few files during my last set of indent changes 👀 They can be done later though.

Oh, which ones? I thought init.lua and choiceNode.lua were the only really relevant files? But yeah, let's do that later 👍

I've done a final set of changes, this time the ? for optional types is also rendered for parameter- and field-lists (which imo looks alright, it's a bit weird if the type is short, e.g. ft?: string? looks a bit weird, but generally I feel like it's a tad more readable), and a few final annotations are added.

I've tested that CI still works correctly on my test-repo, and it seems like everything is working! 🥳

I'll merge after you give it one last look @bew :)

[bew]

I'll merge after you give it one last look @bew :)

Be careful what you wish for, I love reviewing PRs and finding things to improve, so it can take a while 😅

Let's say this is my last big review though, it's almost ready for me!

Re-reading parts of this PR, I missed a few files during my last set of indent changes 👀 They can be done later though.

Oh, which ones? I thought init.lua and choiceNode.lua were the only really relevant files? But yeah, let's do that later 👍

I was looking at the other files of that PR that have type annotations changes, like _extra_types.lua, node.lua, snippet.lua, util.lua, ... But yeah the main ones are good.

I didn't read the CI stuff in details, but you're going to 'live with it' so it gotta be good :D

The vimhelp rendering is generally much much better than before (and inline code blocks seems all perfect now! No cut-off in the middle with a newline) ✨
Params description is still not great but for everything else it's a big positive!

I did a full pass on the generated vimhelp file, and noticed 2 (small) issues there that surfaced small issues with the md doc generation.
And another issue with the MD->vimhelp generation that shows we should probably move the general docs about a node into its top documentation instead of in @param ... doc for better readability.

[bew]

Anything else on your radar ?

Appart from this comment about conflicting @class definition it's good to go for me! 🎉 🚀 🚢

[L3MON4D3]

Aaaalright, that's it for now :D
Thank you for spending time on these thorough reviews, they really helped! :)
Definitely feel free to tinker with this too, just let me know if you're tackling something so we don't start on the same thing accidentally :D

[bew]

That was some great collaboration ✨ With me doing thorough reviews of the things I care about (types, readability, coherence), and you being very patient and swiftly implementing most of my suggested changes that fit with your vision of the project, loved it!

I very much love that plugin, it still has a few DX&UX quirks that I hope to fix / get fixed someday, but the fact that something as powerful & flexible as this exists for neovim is so awesome 🤩
Thank you for this!

This PR is a very good step in the right direction for having better types everywhere and nicer DX while writing snippets, and I hope you/we'll add more types & docs on the internals as well (it is a big negative for me that is preventing me to really read how it all works behind the scene, and maybe contribute 🙃)

Rooting for this! 🚀

[L3MON4D3]

That was some great collaboration ✨ With me doing thorough reviews of the things I care about (types, readability, coherence), and you being very patient and swiftly implementing most of my suggested changes that fit with your vision of the project, loved it!

Totally agree, I also enjoyed this 😄

Thank you for this!

I'm very happy there are people like you who really seem to enjoy using luasnip ❤️

This PR is a very good step in the right direction for having better types everywhere and nicer DX while writing snippets, and I hope you/we'll add more types & docs on the internals as well (it is a big negative for me that is preventing me to really read how it all works behind the scene, and maybe contribute 🙃)

Jup, and high time it's fixed :D
I think there are some internal things that may be difficult to express using lua annotations, but most user-facing functions are relatively well-behaved :)

Oh, and I'd love to have one more pair of eyes on the core-parts of luasnip, so if you ever have questions on how something works, shoot, and I'll do my best to answer/better explain the various mechanisms :D