chore(build): auto-generate docs

doc/lazy.nvim.txt

@@ -36,7 +36,9 @@ Table of Contents                                *lazy.nvim-table-of-contents*
   - 📦 Migration Guide           |lazy.nvim-🚀-usage-📦-migration-guide|
   - ⚡ Profiling & Debug         |lazy.nvim-🚀-usage-⚡-profiling-&-debug|
   - 📂 Structuring Your Plugins|lazy.nvim-🚀-usage-📂-structuring-your-plugins|
-8. 📚 Plugin Developers                   |lazy.nvim-📚-plugin-developers|
+8. 🔥 Developers                                 |lazy.nvim-🔥-developers|
+  - Best Practices                  |lazy.nvim-🔥-developers-best-practices|
+  - Building                              |lazy.nvim-🔥-developers-building|
 9. Links                                                     |lazy.nvim-links|
 
 ==============================================================================
@@ -46,19 +48,28 @@ Table of Contents                                *lazy.nvim-table-of-contents*
 11.X                                       *lazy.nvim-📰-what’s-new?-11.x*
 
 - **New Website**: There’s a whole new website with a fresh look and improved
-    documentation. Check it out at lazy.nvim <https://lazy.folke.io/>. The GitHub
+    documentation. Check it out at <https://lazy.folke.io>. The GitHub `README.md`
-    `README.md` has been updated to point to the new website. The `vimdoc` contains
+    has been updated to point to the new website. The `vimdoc` contains all the
-    all the information that is available on the website.
+    information that is available on the website.
 - **Spec Resolution & Merging**: the code that resolves a final spec from a
     plugin’s fragments has been rewritten. This should be a tiny bit faster, but
     more importantly, fixes some issues and is easier to maintain.
-- `rocks`: specs can now specify a list of rocks (luarocks
-    <https://luarocks.org/>) that should be installed.
 - Packages <https://lazy.folke.io/packages> can now specify their dependencies
     and configuration using one of:
     - **Lazy**: `lazy.lua` file
     - **Rockspec**: luarocks <https://luarocks.org/> `*-scm-1.rockspec` file <https://github.com/luarocks/luarocks/wiki/Rockspec-format>
     - **Packspec**: `pkg.json` (experimental, since the format <https://github.com/neovim/packspec/issues/41> is not quite there yet)
+- Packages are not limited to just Neovim plugins. You can install any
+    **luarocks** package, like:
+    >lua
+        { "https://github.com/lubyk/yaml" }
+    <
+    Luarocks packages without a `/lua` directory are never lazy-loaded, since
+    it’s just a library.
+- `build` functions or `*.lua` build files (like `build.lua`) now run
+    asynchronously. You can use `coroutine.yield(status_msg)` to show progress.
+    Yielding will also schedule the next `resume` to run in the next tick, so you
+    can do long-running tasks without blocking Neovim.
 
 
 ==============================================================================
@@ -235,9 +246,9 @@ SPEC LOADING                         *lazy.nvim-🔌-plugin-spec-spec-loading*
 
 SPEC SETUP                             *lazy.nvim-🔌-plugin-spec-spec-setup*
 
-  -----------------------------------------------------------------------------------------------------
+  ----------------------------------------------------------------------------------------------------
   Property   Type                          Description
-  ---------- ----------------------------- ------------------------------------------------------------
+  ---------- ----------------------------- -----------------------------------------------------------
   init       fun(LazyPlugin)               init functions are always executed during startup
 
   opts       table or                      opts should be a table (will be merged with parent specs),
@@ -258,15 +269,8 @@ SPEC SETUP                             *lazy.nvim-🔌-plugin-spec-spec-setup*
                                            config()
 
   build      fun(LazyPlugin) or string or  build is executed when a plugin is installed or updated.
-             a list of build commands      Before running build, a plugin is first loaded. If it’s a
+             a list of build commands      See Building for more information.
-                                           string it will be run as a shell command. When prefixed with
+  ----------------------------------------------------------------------------------------------------
-                                           : it is a Neovim command. You can also specify a list to
-                                           executed multiple build commands. Some plugins provide their
-                                           own build.lua which is automatically used by lazy. So no
-                                           need to specify a build step for those plugins.
-
-  rocks      string[]?                     Add any luarocks dependencies.
-  -----------------------------------------------------------------------------------------------------
 
 SPEC LAZY LOADING               *lazy.nvim-🔌-plugin-spec-spec-lazy-loading*
 
@@ -535,8 +539,8 @@ dependencies and configuration. Syntax is the same as any plugin spec.
 
 ROCKSPEC                                    *lazy.nvim-📦-packages-rockspec*
 
-When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will
+When a plugin contains a `*-1.rockspec` file, **lazy.nvim** will automatically
-automatically load its `rocks` </spec#setup> dependencies.
+build the rock and its dependencies.
 
 
 PACKSPEC                                    *lazy.nvim-📦-packages-packspec*
@@ -1175,17 +1179,49 @@ spec.
 
 
 ==============================================================================
-8. 📚 Plugin Developers                   *lazy.nvim-📚-plugin-developers*
+8. 🔥 Developers                                 *lazy.nvim-🔥-developers*
 
 To make it easier for users to install your plugin, you can include a package
 spec </packages> in your repo.
 
-If your plugin needs a build step, you can specify this in your **package
-file**, or create a file `build.lua` or `build/init.lua` in the root of your
-repo. This file will be loaded when the plugin is installed or updated.
 
-This makes it easier for users, as they no longer need to specify a `build`
+BEST PRACTICES                      *lazy.nvim-🔥-developers-best-practices*
-command.
+
+- If your plugin needs `setup()`, then create a simple `lazy.lua` file like this:
+    >lua
+          return { "me/my-plugin", opts = {} }
+    <
+- Plugins that are pure lua libraries should be lazy-loaded with `lazy = true`.
+    >lua
+        { "nvim-lua/plenary.nvim", lazy = true }
+    <
+- Only use `dependencies` if a plugin needs the dep to be installed **AND**
+    loaded. Lua plugins/libraries are automatically loaded when they are
+    `require()`d, so they don’t need to be in `dependencies`.
+- Inside a `build` function or `*.lua` build file, use
+    `coroutine.yield(status_msg)` to show progress.
+- Don’t change the `cwd` in your build function, since builds run in parallel
+    and changing the `cwd` will affect other builds.
+
+
+BUILDING                                  *lazy.nvim-🔥-developers-building*
+
+The spec **build** property can be one of the following:
+
+- `fun(plugin: LazyPlugin)`: a function that builds the plugin.
+- `*.lua`: a Lua file that builds the plugin (like `build.lua`)
+- `":Command"`: a Neovim command
+- `"rockspec"`: this will run `luarocks make` in the plugin’s directory
+    This is automatically set by the `rockspec` package </packages> source.
+- any other **string** will be run as a shell command
+- a `list` of any of the above to run multiple build steps
+- if no `build` is specified, but a `build.lua` file exists, that will be used instead.
+
+Build functions and `*.lua` files run asynchronously in a coroutine. Use
+`coroutine.yield(status_msg)` to show progress. Yielding will also schedule the
+next `coroutine.resume()` to run in the next tick, so you can do long-running
+tasks without blocking Neovim.
+
 
 ==============================================================================
 9. Links                                                     *lazy.nvim-links*