From 7b837fb9d38269d080423bb3d856f37bedd917d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Fri, 13 Mar 2015 19:27:34 +0100 Subject: [PATCH 1/8] Add folder_include_patterns and file_include_patterns Extend the documentation of project folder declaration explaining a bit further it's optional values, and adding two that were not being mentioned Please note, english is not my first language. It would be appreciated if you could read and ammend the changes if they happen to sound weird or something. --- source/file_management/file_management.rst | 51 +++++++++++++++++++--- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index cd5d79a..1ca4541 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -223,11 +223,52 @@ 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, and understand basic globbing syntax, such as "*.html". + + The ones that include files and folders, work by excluding + everything first, so that in the end only what they specify + gets shown. After those, the ones that exclude folders apply, + though with lesser precedence. + + Note that a pattern that includes any folder in the project + directory will not automatically include every of it's sub-folders, + but including theese will include any other descendants. + + 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. But, the folder + "bar" inside the "folder "foo" that resides in the project folder + will not be included automatically, whereas another folder called + "bar" or any other name in some other "foo" folder nested deeper + **wll** be included by this definition. If you want to include + every sub-folder form a folder residing in the project folder, + 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 precedence over includes. + Folders may also be given a ``name`` that will appear in the side bar. From d7a90ee5373c29f190b0e6071cfe3fe2c03725d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 01:51:21 +0100 Subject: [PATCH 2/8] Edited project file and folder pattern rules explanation As per some comments made, I've tried my best to make the explacantion a bit clearer, and added the suggested edits. --- source/file_management/file_management.rst | 81 +++++++++++++++++----- 1 file changed, 62 insertions(+), 19 deletions(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index 1ca4541..f6ee305 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -230,16 +230,34 @@ and ``build_systems``, for project-specific build systems. 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, and understand basic globbing syntax, such as "*.html". + 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. - The ones that include files and folders, work by excluding - everything first, so that in the end only what they specify - gets shown. After those, the ones that exclude folders apply, - though with lesser precedence. + 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 project - directory will not automatically include every of it's sub-folders, - but including theese will include any other descendants. + 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: @@ -253,21 +271,46 @@ and ``build_systems``, for project-specific build systems. } } - If the folder "foo" is included, that will by itself include + If the folder :file:`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. But, the folder - "bar" inside the "folder "foo" that resides in the project folder - will not be included automatically, whereas another folder called - "bar" or any other name in some other "foo" folder nested deeper - **wll** be included by this definition. If you want to include - every sub-folder form a folder residing in the project folder, - you can use something like "["foo", foo/*]". + 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 :file:`foo` folder included, but if some other rules applied, + any folder called :file:`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 :file:`foo` of :file:`baz`, :file:`baz/foo`, + would also be included, ans 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 precedence over includes. + the use of ``folder_exclude_patterns``, no matter the specificity + of the rule (for example :file:`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. From 08c7c94b5a8ff41493cf1ecb69d75efccfad4239 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 01:56:09 +0100 Subject: [PATCH 3/8] Little syntax mistakes and syle editions --- source/file_management/file_management.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index f6ee305..3b0c1eb 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -241,7 +241,7 @@ and ``build_systems``, for project-specific build systems. 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 + 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. @@ -274,8 +274,8 @@ and ``build_systems``, for project-specific build systems. If the folder :file:`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 rules, and no :file:`foo` children are included by this rule + when :file:`foo` is in the project folder (level 0), there is actually no other :file:`foo` folder included, but if some other rules applied, any folder called :file:`foo` could be included because of this rule. It depends on if they include top level folders or some other From db0e6bf8fc133a7a5f80e175cfc2ccf18378fdc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 02:15:49 +0100 Subject: [PATCH 4/8] Fixed the examples not being shown --- source/file_management/file_management.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index 3b0c1eb..e9d408d 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -262,6 +262,7 @@ and ``build_systems``, for project-specific build systems. For example, consider adding the following to a folder: .. sourcecode:: javascript + { "folders": [ @@ -284,6 +285,7 @@ and ``build_systems``, for project-specific build systems. Let's modify the example ab bit: .. sourcecode:: javascript + { "folders": [ From 60e14c78b28a917a61aae658eea43967fc98452f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 02:25:12 +0100 Subject: [PATCH 5/8] Removed :file:, It doesn't seem to work --- source/file_management/file_management.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index e9d408d..8867396 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -272,13 +272,13 @@ and ``build_systems``, for project-specific build systems. } } - If the folder :file:`foo` is included, that will by itself include + 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 :file:`foo` children are included by this rule - when :file:`foo` is in the project folder (level 0), there is actually - no other :file:`foo` folder included, but if some other rules applied, - any folder called :file:`foo` could be included because of this rule. + 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. @@ -299,7 +299,7 @@ and ``build_systems``, for project-specific build systems. } Folders "foo" and "bar" at level 0 are included. - But a sub-folder :file:`foo` of :file:`baz`, :file:`baz/foo`, + But a sub-folder `foo` of `baz`, `baz/foo`, would also be included, ans since this folder is not level 0, so would all of it's sub-folders, and their sub-folders, and so on. @@ -311,7 +311,7 @@ and ``build_systems``, for project-specific build systems. 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 :file:`baz/bar/foo`). Consider that + of the rule (for example `baz/bar/foo`). Consider that includes have higher precedence over excludes. Folders may also be given a ``name`` From 7df8c4379032030f10097119572f1ee7d94dcdd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 02:35:27 +0100 Subject: [PATCH 6/8] made folders inline code --- source/file_management/file_management.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index 8867396..726bfe0 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -231,7 +231,7 @@ and ``build_systems``, for project-specific build systems. ``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". + 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 @@ -272,13 +272,13 @@ and ``build_systems``, for project-specific build systems. } } - If the folder `foo` is included, that will by itself include + 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. + 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. @@ -298,8 +298,8 @@ and ``build_systems``, for project-specific build systems. } } - Folders "foo" and "bar" at level 0 are included. - But a sub-folder `foo` of `baz`, `baz/foo`, + Folders ``foo`` and ``bar`` at level 0 are included. + But a sub-folder ``foo`` of ``baz``, ``baz/foo``, would also be included, ans since this folder is not level 0, so would all of it's sub-folders, and their sub-folders, and so on. From 021f5bebd2da950286d314d4551e73cafe29adef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 02:36:55 +0100 Subject: [PATCH 7/8] fixed another typo --- source/file_management/file_management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index 726bfe0..10f01c6 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -300,7 +300,7 @@ and ``build_systems``, for project-specific build systems. Folders ``foo`` and ``bar`` at level 0 are included. But a sub-folder ``foo`` of ``baz``, ``baz/foo``, - would also be included, ans since this folder is not level 0, + 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. From 6a55b356b4b4d567c37f8fb4a32e028d05f0163a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fernando=20H-T=20Gold=C3=A1raz?= Date: Sat, 14 Mar 2015 02:39:55 +0100 Subject: [PATCH 8/8] fixed one last folder reference --- source/file_management/file_management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/file_management/file_management.rst b/source/file_management/file_management.rst index 10f01c6..f7c3860 100644 --- a/source/file_management/file_management.rst +++ b/source/file_management/file_management.rst @@ -309,7 +309,7 @@ and ``build_systems``, for project-specific build systems. 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 + 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.