Do we need to track duplicated plugin descriptions in `options.md` & `plugins.md`? about micro HOT 3 OPEN

I am currently working on a little utility that automatically generates the markdown docs for the plugin API exposed in initlua.go. It's going to take a couple more good days of work until I have a proof of concept, but if that works out well, I don't think it would be too hard to extend it to also generate docs for the available options. Does that sound like a good direction for me to keep exploring?

from micro.

Currently sounds a bit overdone. At the end it still exists twice and most probably not everyone does the "editing" of the doc via the utility/tool/script etc.
But hey, at least it would be cool to know that everything is complete and nothing missing.

from micro.

Yeah, the main reason I'm doing the thing in the first place is so that we can have nice docs for plugin authors that cover the parts of the API that are currently scattered around on pkg.go.dev. I'm also hoping that it would be less work in the long run, because I'm going to source all of the documentation from the comments that already exist in the codebase.

Either way, I'll host the thing on github pages whenever it's done, as a sort of unofficial plugin reference. If it works out well, maybe we can reconsider, but I do concur that it might be overkill. I just get a bit excited about using code as data like that :)

Back on topic:

There are already votes against the removal:

I think these should be kept because someone who is autocompleting set could try to search for them in options.md to figure out what they mean. It's not immediately obvious (partly due to unfortunate naming of the plugins) that they should be looking at plugins.md instead.

I think this makes a lot of sense, even though it kinda sucks that things need to be maintained in two separate places. In fact, I totally missed that in #3240. I'll have to check if it needs to be corrected.

Maybe plugins.md could just track the list of plugins, without the descriptions? Perhaps with links included? Like so:

• autoclose
• comment
• ftoptions
• linter
• literate
• status
• diff

(I realize that this doesn't actually solve the duplication at all, but at least like this there is some added value?)

from micro.