Add test and docs about includes (#796)

closes #794

Makefile

@@ -132,6 +132,7 @@ test_examples:
 	cd example/issues/729_use_default_when_setting_is_blank;pwd;python app.py
 	cd example/issues/741_envvars_ignored;pwd;sh recreate.sh
 	cd example/issues/705_flask_dynaconf_init;pwd;make test;make clean
+	cd example/issues/794_includes;pwd;python app.py
 
 test_vault:
 	# @cd example/vault;pwd;python write.py

docs/configuration.md

@@ -208,6 +208,11 @@ After loading the files specified in `settings_files` dynaconf will load all the
     ```
     **Includes allows the use of globs**
 
+!!! warning 
+    includes are loaded relative to the first loaded file, so if you have a `settings_files=['conf/settings.toml']` and `includes=["*.yaml"]`
+    the yaml files will be loaded relative to the `conf` folder. Unless you specify the absolute path or pass `root_path` to the Dynaconf
+    initializer.
+
 ---
 
 ### **loaders**

docs/settings_files.md

@@ -133,6 +133,10 @@ key = value
 anotherkey = value
 ```
 
+!!! note
+    The paths passed to includes are relative to the `root_path` of Dynaconf instance or if that is not set, relative
+    to the directory where the first loaded file is located, includes also accepts globs and absolute paths.
+
 ---
 
 ## Layered environments on files

dynaconf/base.py

@@ -1074,18 +1074,16 @@ def load_file(self, path=None, env=None, silent=True, key=None):
                     # continue the loop.
                     continue
 
-                # python 3.6 does not resolve Pathlib basedirs
-                # issue #494
                 root_dir = str(self._root_path or os.getcwd())
+
+                # Issue #494
                 if (
                     isinstance(_filename, Path)
                     and str(_filename.parent) in root_dir
                 ):  # pragma: no cover
                     filepath = str(_filename)
                 else:
-                    filepath = os.path.join(
-                        self._root_path or os.getcwd(), str(_filename)
-                    )
+                    filepath = os.path.join(root_dir, str(_filename))
 
                 paths = [
                     p
@@ -1095,6 +1093,7 @@ def load_file(self, path=None, env=None, silent=True, key=None):
                 local_paths = [
                     p for p in sorted(glob.glob(filepath)) if ".local." in p
                 ]
+
                 # Handle possible *.globs sorted alphanumeric
                 for path in paths + local_paths:
                     if path in already_loaded:  # pragma: no cover

example/issues/794_includes/app.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+
+from dynaconf import Dynaconf
+
+# ISSUE 794
+# WHEN USING INCLUDES
+# THE INCLUDES ARE LOADED RELATIVE TO
+# THE FIRST LOADED FILE `conf/settings.toml`
+settings = Dynaconf(
+    settings_files=["conf/settings.toml", "conf/.secrets.toml"],
+    includes=["**/*.toml"],
+)
+
+assert settings.a == 3
+assert settings.b == 2
+assert settings.included_host == "0.0.0.0"
+
+
+# SO..
+# WHEN USING INCLUDES IT IS RECOMMENDED
+# TO SET THE ROOT PATH TO THE DIRECTORY
+# WHERE THE SCRIPT IS RUNNING
+# OR PASS AN ABSOLUTE PATH TO THE root_path or includes
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+settings_with_root_path = Dynaconf(
+    root_path=HERE,
+    settings_files=["conf/settings.toml", "conf/.secrets.toml"],
+    includes=["conf/**/*.toml"],
+)
+
+assert settings_with_root_path.a == 3
+assert settings_with_root_path.b == 2
+assert settings_with_root_path.included_host == "0.0.0.0"

example/issues/794_includes/conf/database/postgre.toml

@@ -0,0 +1 @@
+included_host="0.0.0.0"

example/issues/794_includes/conf/settings.toml

@@ -0,0 +1,2 @@
+a=3
+b=2