stevearc/nvim_doc_tools

use `lua-language-server --docs`

Closed this issue · 1 comments

mehalter commented

Hey! I have been following this repository a bit to see if I could use it potentially for some of AstroNvim's stuff because the results are super nice. I ended up not and using with a core feature of lua-language-server I found that the language server is actually able to generate and output the documentation directly. I'm not sure if you know about this, but it might be nice if you want to alleviate some of your development pressure here when it comes to parsing doc strings manually.

Here is the documentation for it: https://github.com/LuaLS/lua-language-server/wiki/Export-Documentation

It actually generates Markdown as well as a structured JSON for post processing so it's quite powerful if you wanted to just use it for the parsing of the docstrings and then do your own markdown generation with the JSON file (I have found the markdown it generates and resulting vimdoc using panvimdoc is not nearly as nice as the outputs you get here).

In the future if I can find the time, I would like to make a general purpose lua-language-server annotation -> vimdoc github action that any plugin can use easily and am definitely looking to use the type of markdown/vimdoc you are generating with this as a reference because they are gorgeous!

If you are curious about what this sort of looks like just doing some very basic stuff with it, I'm using it in some upcoming AstroNvim repos.

Here is the github action job that does the entire API generation + README to vimdoc (the github action is made as a simple reusable workflow so that I can easily share it between plugins and have one location to make updates): https://github.com/AstroNvim/.github/blob/main/.github/workflows/plugin_ci.yml#L42-L91

And here is just the step that just generates the API markdown: https://github.com/AstroNvim/.github/blob/main/.github/workflows/plugin_ci.yml#L51-L76

Finally, here is an example repo that is using this github action with the result:

This isn't really a bug or a feature request or anything important, but I thought you might be interested in this. Feel free to close this immediately!

stevearc commented

Hey, thanks for the kind words!

I think the idea of creating a github action that can auto-generate docs for any plugin is fantastic. In-editor documentation is one of vim's great strengths, and I know many plugins have little or no vim documentation because it's too much of a burden to maintain both markdown and vimdoc. And as you have discovered, the tools for converting one to the other produce non-ideal results.

I originally made this repo because all the other solutions (including the lua-language-server parser) only did 90% of what I wanted. For example, it wouldn't parse and export this as a function:
https://github.com/stevearc/aerial.nvim/blob/master/lua/aerial/init.lua#L295-L300

So at some point I decided it would be easier to write my own parser than try to work with any existing tools. That also allowed me to create a non-standard syntax when I needed it, for example: option table parameters
https://github.com/stevearc/aerial.nvim/blob/2a6498f4b5f8e52557eadbcd2b3f91da8fe438ca/lua/aerial/init.lua#L265-L268

You are of course welcome to use any part of this repo if you find it useful, but I do think that what you're doing with the lua-language-server parser is closer to the ideal solution.