docs(#2934): add nvim_tree.config* classes with generated help and new nvim-tree-icons-highlighting help section

[alex-courtis]

fixes #2934

I'd be most grateful for your review @gegoune ... and apologies for the massive PR. There are no code changes, just annotations/docs.

I can't ask anyone to review the whole thing, but I'd be most grateful for a review of the overall structure, format conventions, dev/CI scripts. Also comments on the contentious bits please.

An AI tool was used, however it added very little value, only able to create the skeleton. It made a mess of all documentation, which I ended up doing with scripts.

In scope:

• Create _meta classes for all config
• Generate help from those classes - *nvim_tree.config* is deleted and rewritten
• Contentious: remove indices, table of contents and capitalised sections snake cased sections, to follow Nvim doc standards "Type |gO| to see the table of contents."
• Refactored a lot of documentation for readability
• Compressed a lot of documentation into single sections
• Added *nvim-tree-icons-highlighting* to link everything together
• Created temporary *nvim-tree-hidden-display* to be addressed via Documentation: Renderer.HiddenDisplay luals Annotations And Help #3243
• Moved default config to end

Out of scope:

• #3231 step 1: Annotate Usages Of Config Classes #3242
• Documentation: API luals Annotations And Help #3088
• Documentation: Decorator luals Annotations And Help #3241
• Documentation: Renderer.HiddenDisplay luals Annotations And Help #3243

CI and build:

• Really contentious: CI is a lot slower
• scripts/gen_vimdoc.sh uses Nvim source (not compiled) to generate all class docs from _meta
  • Contentious: it is manually configured via gen_vimdoc_config.lua which is hackily injected into Nvim's src/gen/gen_vimdoc.lua
• scripts/lintdoc.sh uses Nvim compiled source to lint. The value for us is validating tags.

Notable annoyances:

• Enums and aliases are not generated. They have been manually annotated e.g. *nvim_tree.Config.View.WidthSpec*
• Field types are not tagged and thus cannot be navigated to. Tags have been manually added e.g. *nvim_tree.config.bookmarks* added to *nvim_tree.config* {bookmarks}
• Contentious: Nvim latest and stable differ in the blank lines they generate in the help output. I've ignored those with a --ignore-blank-lines in the help-check target.

TODO

• split meta_/config.lua into multiple files for sections and easier maintenance and ordering of sections
• rename hijack_unnamed_buffer_when_opening as it messes up the formatting of other fields moved root Config field descriptions into class description for readability
• use (exact) classes for better UX when creating config doesn't add value as it doesn't prevent invalid fields when defining your nvim_tree.Config
• move things out of fields (hard to read) into class descriptions
• decide on lower case classnames, as nvim does for anything that's a parameter there's no real convention for other plugins, capitalised classnames match nvim-tree and general lua OO
• @type or @param everything that uses nvim_tree.Config
• ensure all links actually work - add to help check
• add gen and lint to CI
• add gen to CONTRIBUTING.md
• add an on-attach type did not end up necessary
• revert changes to api options classes, to be done in Documentation: API luals Annotations And Help #3088

[gegoune]

Great job! LGTM with single worry: anchors are no longer mapped 1:1 to corresponding options, won't that be an issue?

[gegoune]

Currently we have nvim-tree.hijack_directories.enable which maps 1:1 to actual option, won't it be bit confusing being HijackDirectories now?

[alex-courtis]

Ah yes, I didn't think of that. We had it for every config option in the hierarchy and should continue to have that.

I'll see what I can do with gen_vimdoc_config.lua. tags and sections are quite configurable. Possibilities:

1. Try to change the class names, lowercase etc. to match. Nvim kind of does that.
2. Add extra tags to each class.
3. Change the section tags e.g. *nvim-tree-config-hijack-directories* -> *nvim-tree.hijack_directories*

[alex-courtis]

1 worked out reasonably well, class and alias names all match the options:

• we can :help actions.expand_all or :help nvim_tree.config.actions.expand_all
• we can't :help use_system_clipboard, we have to :helpgrep use_system_clipboard as the generator can't do it
• we can't use nvim-tree in class or function names as lua can't do dashes, hence it's nvim_tree.config.hijack_directories

I left a note at the top: https://github.com/nvim-tree/nvim-tree.lua/pull/3235/changes#diff-b5b2d1abcb86ead5a2319f7e065a7545b834a407cc9f420590d7acebb285fca9R1-R10

Edit: I moved the default config to the end, so that helpgrep finds the config class doc first.

Good to go?

[gegoune]

Go for it, nicely done!