From 495a291c17c8b343f7d58c369f629502d13344aa Mon Sep 17 00:00:00 2001 From: Julian-o Date: Fri, 8 Sep 2023 16:25:52 +1000 Subject: [PATCH] Rewrite section on include/excludes --- docs/source/specifications.rst | 56 +++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/docs/source/specifications.rst b/docs/source/specifications.rst index 5c93f93d2..24f4de7f2 100644 --- a/docs/source/specifications.rst +++ b/docs/source/specifications.rst @@ -32,32 +32,46 @@ Section [app] The location must be a directory that contains a `main.py` file. It defaults to the directory where `buildozer.spec` is. -- `source.include_exts`: List, file extensions to include. - - By default, not all files in your `source.dir` are included, but only some - of them (`py,png,jpg,kv,atlas`), depending on the extension. Feel free to - add your own extensions, or use an empty value if you want to include - everything. - -- `source.exclude_exts`: List, file extensions to exclude. - - In contrary to `source.include_exts`, you could include all the files you - want except the ones that end with an extension listed in this token. If - empty, no files will be excluded based on their extensions. - -- `source.exclude_dirs`: List, directories to exclude. - - Same as `source.exclude_exts`, but for directories. You can exclude your +- Source Inclusion/Exclusion options. + + - `source.include_exts`: List, file extensions to include. + - `source.exclude_exts`: List, file extensions to exclude, even if included by + `source.include_exts` + - `source.exclude_dirs`: List, directories to exclude. + - `source.exclude_patterns`: List, files to exclude if they match a pattern. + - `source.include_patterns`: List, files to include if they match a pattern, even if excluded by + `source.exclude_dirs` or `source.exclude_patterns` + + By default, not all files are in your `source.dir` are included. You can + use these options to alter which files are included in your app and which + are excluded. + + Directories and files starting with a "." are always excluded; this cannot be + overridden. + + Files that have an extension that is not in `source.include_exts` are excluded. + (The default suggestion is `py,png,jpg,kv,atlas`. You may want to include other + file extensions such as resource files: gif, xml, mp3, etc.) File names that + have no extension (i.e contain no ".") are not excluded here. + `source.exclude_exts` takes priority over `source.include_exts` - it excludes any listed extensions + that were previously included. + + Files and directories in directories listed in `source.exclude_dirs` are excluded. For example, you can exclude your `tests` and `bin` directory with:: - source.exclude_dirs = tests, bin + source.exclude_dirs = tests, bin + + `source.exclude_patterns` are also excluded. This is useful for excluding individual + files. For example:: -- `source.exclude_patterns`: List, files to exclude if they match a pattern. + source.exclude_patterns = license - If you have a more complex application layout, you might need a pattern to - exclude files. It also works if you don't have a pattern. For example:: + These dir and pattern exclusions may be overridden with + `source.include_patterns` - files and directories that match will once again be included. - source.exclude_patterns = license,images/originals/* + However, `source.include_patterns` does not override the `source.include_exts` nor + `source.exclude_exts`. `source.include_patterns` also cannot be used to include files or directories that + start with ".") - `version.regex`: Regex, Regular expression to capture the version in `version.filename`.