docs(#3088): unify help generation and lint into vimdoc.sh, generation uses nvim source build to execute (#3260)

* docs(#3241): unify help generation and lint into vimdoc.sh, generation uses nvim source build to execute

* docs(#3241): unify help generation and lint into vimdoc.sh, generation uses nvim source build to execute

* docs(#3241): unify help generation and lint into vimdoc.sh, generation uses nvim source build to execute

* docs(#3241): unify help generation and lint into vimdoc.sh, generation uses nvim source build to execute

Author: alex-courtis

.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 doc
           make lintdoc
 
       - run: make help-check

CONTRIBUTING.md

@@ -136,7 +136,7 @@ Help is generated for:
 
 Please add or update documentation when you make changes, see `:help dev-lua-doc` for docstring format.
 
-`scripts/gen_vimdoc_config.lua` contains the manifest of help sources.
+`scripts/vimdoc_config.lua` contains the manifest of help sources.
 
 ### Config And Mappings
 
@@ -160,7 +160,7 @@ make help-update
     - `*nvim-tree-mappings-default*`
     - `*nvim-tree-quickstart-help*`
 
-- `scripts/gen_vimdoc.sh`
+- `scripts/vimdoc.sh doc`
   - Remove content starting at `*nvim-tree-config*`
   - Generate config classes `*nvim-tree-config*`
   - Generate API `*nvim-tree-api*`
@@ -175,7 +175,7 @@ make help-check
 
 - 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/lintdoc.sh` to check for no broken links etc.
+- Lints `doc/nvim-tree-lua.txt` using `scripts/vimdoc.sh lintdoc` to check for no broken links etc.
 
 # Windows
 

Makefile

@@ -34,15 +34,15 @@ style-fix:
 # utility
 #
 help-update:
-	scripts/gen_vimdoc.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
 
 

scripts/gen_vimdoc.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env sh
+
+# Wrapper around Nvim make targets:
+#
+# make doc - gen_vimdoc.lua
+#   Generates doc/nvim-tree-lua.txt 
+#   Uses nvim-tree sources defined in scripts/vimdoc_config.lua
+#   Shims above into src/gen/gen_vimdoc.lua, replacing Nvim's config.
+#
+# make lintdoc - lintdoc.lua
+#   Validates doc/nvim-tree-lua.txt 
+#   Desired:
+#   - tags valid
+#   - links valid
+#   Also:
+#   - brand spelling, notably Nvim and Lua
+#
+# There are some hardcoded expectations which we work around as commented.
+
+set -e
+
+if [ $# -ne 1 ] || [ "${1}" != "doc" ] && [ "${1}" != "lintdoc" ]; then
+	echo "usage: ${0} <doc|lintdoc>" 1>&2
+	exit 1
+fi
+
+DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable"
+
+if [ ! -d "lua/nvim-tree" ]; then
+	echo "Must be run from nvim-tree root" 1>&2
+	exit 1
+fi
+
+if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then
+	export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}"
+fi
+
+if [ ! -d "${DIR_NVIM_SRC}" ]; then
+	cat << EOM
+
+Nvim source v0.11+ is required to run ${0}
+
+Unavailable: ${DIR_NVIM_SRC_DEF} or \$DIR_NVIM_SRC=${DIR_NVIM_SRC}
+
+Please:
+  mkdir -p ${DIR_NVIM_SRC_DEF}
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}")
+	or use your own e.g.
+  export DIR_NVIM_SRC="\${HOME}/src/neovim"
+
+EOM
+exit 1
+fi
+
+cleanup() {
+	# remove source link
+	rm -fv "${DIR_NVIM_SRC}/runtime/lua/nvim_tree"
+
+	# remove our config
+	rm -fv "${DIR_NVIM_SRC}/src/gen/vimdoc_config.lua"
+
+	# remove generated help
+	rm -fv "${DIR_NVIM_SRC}/runtime/doc/nvim-tree-lua.txt"
+
+	# revert generator if present
+	if [ -f "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua.org" ]; then
+		mv -v "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua.org" "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua"
+	fi
+}
+
+# clean up any previous failed runs
+cleanup
+
+# runtime/doc is hardcoded, copy the help in
+cp -v "doc/nvim-tree-lua.txt" "${DIR_NVIM_SRC}/runtime/doc"
+
+# setup doc generation
+if [ "${1}" = "doc" ]; then
+	# runtime/lua is available, link our sources in there
+	# gen_vimdoc.lua doesn't like dashes in lua module names
+	#   -> use nvim_tree instead of nvim-tree
+	ln -sv "${PWD}/lua/nvim-tree" "${DIR_NVIM_SRC}/runtime/lua/nvim_tree"
+
+	# modify gen_vimdoc.lua to use our config, backing up original
+	cp "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua" "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua.org"
+	sed -i -E 's/spairs\(config\)/spairs\(require("gen.vimdoc_config")\)/g' "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua"
+
+	# copy our config
+	cp -v "scripts/vimdoc_config.lua" "${DIR_NVIM_SRC}/src/gen"
+fi
+
+# run from within Nvim source
+cd "${DIR_NVIM_SRC}"
+make "${1}"
+cd -
+
+# copy the generated help out
+cp -v "${DIR_NVIM_SRC}/runtime/doc/nvim-tree-lua.txt" "doc"
+
+# cleanup as everything succeeded
+cleanup

scripts/lintdoc.sh

@@ -1,6 +1,6 @@
 --nvim-tree configuration for Nvim's gen_vimdoc.lua
 --Returned config is injected into the above.
---See gen_vimdoc.sh
+--Execute with `make doc`, see scripts/vimdoc.sh for details.
 
 --gen_vimdoc keys by filename:   -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
 --Hence we must ensure that filenames are unique within each nvim.gen_vimdoc.Config[]