Add folder_include_patterns and file_include_patterns

source/file_management/file_management.rst

@@ -223,11 +223,97 @@ and ``build_systems``, for project-specific build systems.
 
 
 **Folders**
-    Each folder must have a ``path``,
-    and may optionally have a ``folder_exclude_patterns``
-and ``file_exclude_patterns`` setting.
-    The path may be relative to the project directory,
-    or an absolute path.
+    Each folder must have a ``path``, that may be absolute or
+    relative. In the latter case it will be relative to the
+    project directory.
+
+    There are also the optional properties ``folder_include_patterns``,
+    ``file_include_patterns``, ``folder_exclude_patterns``
+    and ``file_exclude_patterns``. They all admit an array of strings
+    as values, each conforming a pattern that allows some basic
+    globbing syntax, such as ``*.html``.
+    They can be used to modify what files will be shown in the sidebar
+    for this project. With the help of these rules, you can configure
+    your project to work with and only with almost any subset of
+    files you can imagine.
+
+    Of these four rules, the rules that include files and folders,
+    work by excluding every file (or folder) first, so that in the end,
+    only the files/folders they specify become visible in the sidebar.
+    ``folder_include_patterns`` and ``file_include_patterns`` apply first,
+    and ``folder_exclude_patterns`` while ``file_exclude_patterns`` apply
+    after them, though with a somewhat lesser precedence, meaning that
+    it may not always be possible to exlude some files or folders
+    prevously included by the incude rules.
+
+    Note that a pattern that includes any folder in the root of the project,
+    that is, a folder that lives right on the project folder, 
+    will not automatically include every of it's sub-folders. By itself,
+    such a rule will make those sub-folders hidden.
+    In contrast, including these sub-folders **will** include any
+    other of their descendants, and so, you will be able to see all of their
+    sub-folders, whatever their nesting level.
+
+    In other words, at level 0 (right on the project folder),
+    including a folder hides other folders conained within (level 1 folders).
+    But at any other level, for example at level 1, including a folder will
+    include all of it's descendants, (level 2, 3, ..., n)
+
+    For example, consider adding the following to a folder:
+
+    .. sourcecode:: javascript
+
+        {
+            "folders":
+            [
+                {
+                    "path": ".",
+                    "folder_include_patterns": ["foo"]
+                }
+        }
+
+    If the folder ``foo`` is included, that will by itself include
+    any  other folder whose name starts with foo, whether it is in
+    the project folder, or inside some other folder. Since there are
+    no other rules, and no ``foo`` children are included by this rule
+    when ``foo`` is in the project folder (level 0), there is actually
+    no other ``foo`` folder included, but if some other rules applied,
+    any folder called ``foo`` could be included because of this rule.
+    It depends on if they include top level folders or some other
+    higher level (deeper nested) folders.
+
+    Let's modify the example ab bit:
+
+    .. sourcecode:: javascript
+
+        {
+            "folders":
+            [
+                {
+                    "path": ".",
+                    "folder_include_patterns": [
+                    	"foo",
+                    	"baz"
+                    ]
+                }
+        }
+
+    Folders ``foo`` and ``bar`` at level 0 are included.
+    But a sub-folder ``foo`` of ``baz``, ``baz/foo``,
+    would also be included, and since this folder is not level 0,
+    so would all of it's sub-folders, and their sub-folders,
+    and so on.
+
+    As a side note, if you want to include every sub-folder from a
+    folder residing in the project folder (level 0), you can use
+    something like ``["foo", foo/*]``.
+
+    Note also that a rule like the one in the prevous example would
+    not let us exclude an already included ``foo`` sub-folder through
+    the use of ``folder_exclude_patterns``, no matter the specificity
+    of the rule (for example `baz/bar/foo`). Consider that
+    includes have higher precedence over excludes.
+
     Folders may also be given a ``name``
     that will appear in the side bar.