From 114f60ca5394cd3c59987b8d4eca8a24d08df31e Mon Sep 17 00:00:00 2001 From: Robert Dailey Date: Sun, 21 Apr 2024 16:10:12 -0500 Subject: [PATCH] Documentation for new includes directory --- docs/_include-templates-dir.md | 34 +++++++++++++++++++++++++++ docs/behavior/include.md | 31 ++---------------------- docs/file-structure.md | 15 +++++++++--- docs/schema-validation.md | 2 +- docs/yaml/config-reference/include.md | 14 +++++------ 5 files changed, 56 insertions(+), 40 deletions(-) create mode 100644 docs/_include-templates-dir.md diff --git a/docs/_include-templates-dir.md b/docs/_include-templates-dir.md new file mode 100644 index 0000000..1f1295c --- /dev/null +++ b/docs/_include-templates-dir.md @@ -0,0 +1,34 @@ +A directory named `includes` exists under the application data directory where local [include +templates][configdirective] may be placed. Any relative paths to include templates will start at +this directory. + +For example, if I have the following include directive in a configuration file named `foo.yml`: + +```yml +include: + - config: bar/reusable.yml +``` + +The expected file structure of my `includes` directory would be visualized as follows: + +```txt +. +├── configs/ +│ └── foo.yml +└── includes/ + └── bar/ + └── reusable.yml +``` + +For more information about include templates, see the respective [behaviors page][include]. + +:::caution + +Configuration files (non-includes) should *not* be placed here; use the [`configs`][configsdir] +directory for those. + +::: + +[include]: /yaml/config-reference/include.md +[configdirective]: /yaml/config-reference/include.md#config +[configsdir]: /file-structure.md#config-directory diff --git a/docs/behavior/include.md b/docs/behavior/include.md index d86d606..2d32d20 100644 --- a/docs/behavior/include.md +++ b/docs/behavior/include.md @@ -393,33 +393,6 @@ custom_formats: ### Include File Structure {#file-structure} -This section covers the currently recommended file structure for local YAML includes. +import IncludeDirectory from '../_include-templates-dir.md' -Recyclarr does not recursively scan for configuration YAML files in the [`configs` -subdirectory][configdir]. This means that you can structure local include YAML files into -subdirectories inside `configs`. This allows the convenient usage of relative paths when using the -[`config` include directive][configdirective]. - -As an example, consider this file structure: - -```txt -. -└── configs/ - ├── includes/ - │ └── reusable.yml - └── my-config.yml -``` - -And the `my-config.yml` file has the following include directives: - -```yml -include: - - config: includes/reusable.yml -``` - -Because we have our includes within the `configs` directory, we can easily access them with a -relative path. And since those includes are under a subdirectory, Recyclarr will not scan them and -treat them as top-level configuration YAML files. - -[configdir]: /file-structure.md#config-directory -[configdirective]: /yaml/config-reference/include.md#config + diff --git a/docs/file-structure.md b/docs/file-structure.md index c30d3a8..2314671 100644 --- a/docs/file-structure.md +++ b/docs/file-structure.md @@ -48,7 +48,16 @@ really have an easy way to specify custom CLI arguments. The following requireme `--config` command line argument. This behavior is non-recursive; meaning if you place YAML files in subdirectories under `configs/`, they will not be loaded. - The names of the files are unimportant and can be whatever you want. -- [Include templates][inc] should *not* be placed in this directory; only real configuration files - are supported here. -[inc]: /yaml/config-reference/include.md +:::caution + +Include templates should *not* be placed here; use the [`includes`](#include-directory) directory +instead. + +::: + +## Include Templates Directory {#include-directory} + +import IncludeDirectory from './_include-templates-dir.md' + + diff --git a/docs/schema-validation.md b/docs/schema-validation.md index b2cdd84..c098fcf 100644 --- a/docs/schema-validation.md +++ b/docs/schema-validation.md @@ -16,7 +16,7 @@ much easier. You should be interested in this topic if any of the following poin :::info What's a Schema? -A *schema*, in this case, defines the shape that YAML must conform to. It's a `json` file that +A *schema*, in this case, defines the shape that YAML must conform to. It's a JSON file that describes the different parts of YAML settings, configuration, and other files that Recyclarr uses. Schema *validation* refers to the process of using the schema itself to check for issues in your diff --git a/docs/yaml/config-reference/include.md b/docs/yaml/config-reference/include.md index 75688aa..e770670 100644 --- a/docs/yaml/config-reference/include.md +++ b/docs/yaml/config-reference/include.md @@ -16,7 +16,7 @@ service_type: # Include Configuration include: - template: uhd-bluray-web - - config: includes/my-config.yml + - config: my-config.yml ``` YAML includes are a mechanism to support reusable configurations. Including YAML is the process of @@ -48,22 +48,22 @@ Use this directive to include YAML files on your local filesystem. **Required.** -An absolute or relative path to the YAML file you wish to include. Relative paths start at the -`configs` directory inside the [app data directory][appdata] +An absolute or relative path to the YAML file you wish to include. If relative paths are used, see +the [app data directory][appdata] page for where those files should be located. -[appdata]: /file-structure.md#appdata-directory +[appdata]: /file-structure.md#include-directory ### Examples ```yml include: # An absolute include path - - config: /home/john/my-config.yml + - config: /home/john/my-include.yml # A relative include path # Equivalent absolute path is (on Linux): - # /home/john/.config/recyclarr/configs/include/my-config.yml - - config: include/my-config.yml + # /home/john/.config/recyclarr/includes/my-include.yml + - config: my-include.yml ``` ## Template Includes {#template}