merge branch master

Author: Uanela

.github/workflows/ci.yml

@@ -82,6 +82,7 @@ jobs:
           mkdir -p "${DIR_NVIM_SRC}"
           curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory "${DIR_NVIM_SRC}/.."
           cd "${DIR_NVIM_SRC}"
-          make
+          make doc
+          make lintdoc
 
       - run: make help-check

CONTRIBUTING.md

@@ -18,9 +18,10 @@ markdown-toc --maxdepth=2 -i CONTRIBUTING.md
   * [check](#check)
 - [Diagnostics](#diagnostics)
 - [Backwards Compatibility](#backwards-compatibility)
-- [Documentation](#documentation)
-  * [Config And Mappings](#config-and-mappings)
-  * [API](#api)
+- [:help Documentation](#help-documentation)
+  * [Generated Content](#generated-content)
+  * [Updating And Generating](#updating-and-generating)
+  * [Checking And Linting](#checking-and-linting)
 - [Windows](#windows)
 - [Pull Request](#pull-request)
   * [Subject](#subject)
@@ -60,7 +61,7 @@ make lint
 ## style
 
 1. Runs lua language server `codestyle-check` only, using `.luarc.json` settings
-1. Runs `scripts/doc-comments.sh` to validate annotated documentation
+1. Runs `scripts/doc-comments.sh` to normalise annotated documentation
 
 ```sh
 make style
@@ -86,11 +87,11 @@ Assumes `$VIMRUNTIME` is `/usr/share/nvim/runtime`. Adjust as necessary e.g.
 VIMRUNTIME="/my/path/to/runtime" make check
 ```
 
-If `lua-language-server` is not available or `--check` doesn't function (e.g. Arch Linux 3.9.1-1) you can manually install it as per `ci.yml` e.g.
+If `lua-language-server` is not available or `--check` doesn't function (e.g. Arch Linux 3.9.1-1) you can manually install it as per `ci.yml` using its current `luals_version` e.g.
 
 ```sh
 mkdir luals
-curl -L "https://github.com/LuaLS/lua-language-server/releases/download/3.9.1/lua-language-server-3.9.1-linux-x64.tar.gz" | tar zx --directory luals
+curl -L "https://github.com/LuaLS/lua-language-server/releases/download/3.15.0/lua-language-server-3.15.0-linux-x64.tar.gz" | tar zx --directory luals
 
 PATH="luals/bin:${PATH}" make check
 ```
@@ -119,36 +120,62 @@ else
 end
 ```
 
-# Documentation
+# :help Documentation
 
-## Config And Mappings
+Please update or add to `doc/nvim-tree-lua.txt` as needed.
 
-When adding to or changing:
-1. Default config
-2. `config` classes
-3. `on_attach` default mappings
+## Generated Content
 
-You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source.
+`doc/nvim-tree-lua.txt` content starting at `*nvim-tree-config*` will be replaced with generated content. Do not manually edit that content.
+
+### API and Config
+
+Help is generated for:
+- `nvim_tree.config` classes from `lua/nvim-tree/_meta/config/`
+- `nvim_tree.api` functions from `lua/nvim-tree/_meta/api/`
+
+Please add or update documentation when you make changes, see `:help dev-lua-doc` for docstring format.
+
+`scripts/vimdoc_config.lua` contains the manifest of help sources.
+
+### Config And Mappings
+
+Help is updated for:
+- Default keymap at `keymap.on_attach_default`
+- Default config at `--- default-config-start`
+
+## Updating And Generating
+
+Nvim sources are required. You will be prompted with instructions on fetching and using the sources.
+
+See comments at the start of each script for complete details.
 
 ```sh
 make help-update
 ```
 
-This will:
-1. Update config defaults in `*nvim-tree-setup*`
-2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
-3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
+- `scripts/help-defaults.sh`
+  - Update config defaults `*nvim-tree-config-default*`
+  - Update default mappings:
+    - `*nvim-tree-mappings-default*`
+    - `*nvim-tree-quickstart-help*`
+
+- `scripts/vimdoc.sh doc`
+  - Remove content starting at `*nvim-tree-config*`
+  - Generate config classes `*nvim-tree-config*`
+  - Generate API `*nvim-tree-api*`
+
+## Checking And Linting
+
+This is run in CI. Commit or stage your changes and run:
 
-Commit your changes then run:
 ```sh
 make help-check
 ```
 
-This will re-run `help-update` and check that there are no diffs. It will also lint the documentation, see `lintdoc.sh`
-
-## API
-
-When adding or changing API please update :help nvim-tree-api
+- Re-runs `make help-update`
+- Checks that `git diff` is empty, to ensure that all content has been generated. This is why a stage or commit is necessary.
+- Lints `doc/nvim-tree-lua.txt` using `scripts/vimdoc.sh lintdoc` to check for no broken links etc.
 
 # Windows
 

Makefile

@@ -12,10 +12,8 @@ check: luals
 #
 # subtasks
 #
-# TODO #3241 ensure that decorator is checked - all meta should be valid
 luacheck:
-	luacheck --codes --quiet lua --exclude-files "**/_meta/api_decorator.lua"
-	luacheck --codes --quiet scripts
+	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
 
 style-check:
 	scripts/luals-check.sh codestyle-check
@@ -36,15 +34,15 @@ style-fix:
 # utility
 #
 help-update:
-	scripts/gen_vimdoc.sh
-	scripts/help-update.sh
+	scripts/vimdoc.sh doc
+	scripts/help-defaults.sh
 
 #
 # CI
 # --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts
 #
 help-check: help-update
-	scripts/lintdoc.sh
+	scripts/vimdoc.sh lintdoc
 	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt