Document deprecation of $env.NU_LIB_DIRS (#2101)

* Document deprecation of $env.NU_LIB_DIRS

The $env.NU_LIB_DIRS has been marked deprecated in the nushell source
code for a while now, by default it is an empty list to maintain
compatibility. Users should prefer the constant $NU_LIB_DIRS instead,
which is populated with some things based on environment variables at
nushell startup.

The docs had drifted a bit. This commit serves to update them.

* Apply suggestions from code review

---------

Co-authored-by: James Smith <james@cloudstroller.xyz>
Co-authored-by: Yash Thakur <45539777+ysthakur@users.noreply.github.com>

Author: 3 people

book/configuration.md

@@ -390,12 +390,12 @@ The variables that affect Nushell file locations are:
 
   Once Nushell starts, this value is stored in the `$nu.default-config-dir` constant. See [Using Constants](#using-constants) below.
 
-- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to this value. The `data-dir` is used in several startup tasks:
+- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to `($env.XDG_DATA_HOME)/nushell`. The `data-dir` is used in several startup tasks:
 
-  - `($nu.data-dir)/completions` is added to the `$env.NU_LIB_DIRS` search path.
+  - `($nu.data-dir)/completions` is added to the `const` variable [`$NU_LIB_DIRS`](./special_variables.md#NU_LIB_DIRS). (Note: `$env.NU_LIB_DIRS` is not populated by default and is currently deprecated. See [Special Variables - `$env.NU_LIB_DIRS`](./special_variables.md#env-NU_LIB_DIRS).)
   - `($nu.data-dir)/vendor/autoload` is added as the last path in `nu.vendor-autoload-dirs`. Files in this directory will be read after the other vendor-auto-load directories, thus overriding any of their settings.
 
-  Note that the directory represented by `$nu.data-dir`, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user.
+  Note that the directory represented by `$nu.data-dir`, including any of its subdirectories, are NOT created by default. Creation and use of these directories is up to the user.
 
 - `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-auto-load` directories in the order listed. The first directory in the list is processed first, meaning the last one read will have the ability to override previous definitions.
 

book/modules/creating_modules.md

@@ -305,7 +305,7 @@ Also notice that, because the commands from `increment` and `range-into-list` ar
 
 ## Environment Variables
 
-Modules can define an environment using [`export-env`](/commands/docs/export-env.md). Let's extend our `my-utils` module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the `$env.NU_LIB_DIRS` search path discussed in [Using Modules - Module Path](./using_modules.md#module-path).
+Modules can define an environment using [`export-env`](/commands/docs/export-env.md). Let's extend our `my-utils` module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the `$NU_LIB_DIRS` search path discussed in [Using Modules - Module Path](./using_modules.md#module-path).
 
 ```nu
 # A collection of helpful utility functions

book/modules/using_modules.md

@@ -69,13 +69,13 @@ The path to the module can be:
   Note that the module name (its directory) can end in a `/` (or `\` on Windows), but as with most commands that take a paths (e.g., `cd`), this is completely optional.
   :::
 
-  ::: important Important! Importing modules from `$env.NU_LIB_DIRS`
-  When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the `$env.NU_LIB_DIRS` list.
+  ::: important Important! Importing modules from `$NU_LIB_DIRS` or `$env.NU_LIB_DIRS`
+  When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the constant `$NU_LIB_DIRS` list, and then `$env.NU_LIB_DIRS` (deprecated).
 
   This allows you to install modules to a location that is easily accessible via a relative path regardless of the current directory.
   :::
 
-- An absolute or relative path to a Nushell module file. As above, Nushell will search the `$env.NU_LIB_DIRS` for a matching relative path.
+- An absolute or relative path to a Nushell module file. As above, Nushell will search the constant `$NU_LIB_DIRS` and then `$env.NU_LIB_DIRS` for a matching relative path.
 
   ::: details Example
 

book/special_variables.md

@@ -101,6 +101,12 @@ try {
 
 ### `$env.NU_LIB_DIRS`
 
+::: warning
+
+As of version 0.101.0, this environment variable is marked as deprecated. Users should prefer the `$NU_LIB_DIRS` constant (see below).
+
+:::
+
 A list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also:
 
 - The `$NU_LIB_DIRS` constant below