Add getting started, touch walkthroughs (#2339)

CHANGELOG

@@ -8,6 +8,10 @@ Added the `character` search option to the `imdb_search` builder
 Added ability to use Show-level ratings at the season and episode level for Overlays if the original source does not provide ratings at the season or episode level. This is accomplished using (Special Text Variables)[https://kometa.wiki/en/latest/files/overlays/#special-text-variables] but is not yet available for the `Ratings` Defaults file.
 Add `show_unfiltered` setting to display items which make it through a filter
 
+# Docs
+Added "getting started" page
+Added page to describe all the YAML files
+
 # Defaults
 Fixed incorrect content rating mappings in various Default files
 Fixes an issue where Prime Video overlays/collections would not be built when the `watch_region` is set to AU

docs/kometa/install/docker.md

@@ -5,8 +5,9 @@ This article will walk you through getting Kometa set up and running via Docker.
 1. Installing Docker
 2. Retrieving the image
 3. Setting up the initial config file
-4. Setting up a collection file and creating a couple sample collections
+4. Creating some sample collections using the defaults
-5. Creating a docker container that will keep running in the background
+5. Setting up a collection file and creating a sample collection.
+6. Adding some default overlays.
 
 The specific steps you will be taking:
 

docs/kometa/install/getting_started.md

@@ -0,0 +1,163 @@
+# Getting Started with Kometa
+
+Kometa has a relatively simple startup process. This guide will walk you through the things you *have* to do to get started with Kometa.
+
+## Typical startup problems
+
+Generally, the most common problems that users encounter when starting Kometa are related to finding some complicated config and copy-pasting it without understanding it, or trying to add a whole lot of things at once, again without understanding how the tool works.
+
+The key is to start slow and simple, and build up from there.  Don't get impatient and try to add everything at once.  You'll get there, but it's better to start with a simple setup and build up from there.
+
+An imperfect metaphor would be: "Hey, changing my oil was fun.  I think I'll rebuild the engine next!"
+
+There is a four-hour video that gets a lot of attention and gets held up as evidence that Kometa takes four hours to set up.  This is not true.  The video is a deep dive into the creator's complicated setup that is specific to his requirements.  It starts by setting up a third-party script [written by one of the Kometa team] describing it as a requirement even before installing Kometa.  This script is not required by Kometa in any way.  In any case, the Kometa setup is not a four-hour process.  The setup process is actually quite simple.
+
+From a standing start, you can have Kometa up and running in maybe 10 minutes.
+
+Of course, tuning and tweaking and adding more libraries and more features will take longer, perhaps four hours or more, but the basic setup is quite simple.
+
+## Required steps
+
+There are two required steps:
+
+1. **Install Kometa**
+2. **Create a config file**
+
+### Step 1: Install Kometa
+
+You can run Kometa in one of two ways: running as a Python script on your system, or running as a Docker container.
+
+Running as a Docker container is generally simpler, as you won't have to be concerned about installing Python, or support libraries, or any possible system conflicts generated by those actions.
+
+There is really not much of an "install" process for Kometa.  You will either download some files into a directory and run a script, or you will pull a Docker image and run a container.
+
+You may need to install Python or Docker, but that's not a Kometa-specific requirement.
+
+The Kometa files themselves are self-contained and do not require any installation process beyond downloading them.
+
+Similarly, the docker image is self-contained and does not require any installation process beyond pulling the image.
+
+### Step 2: Create a config file
+
+There are two platform-independent walkthroughs for getting started with Kometa:
+
+1. [Local Python script](./local.md)
+2. [Docker container](./docker.md)
+
+Both of those walkthroughs will get you up and running with Kometa in a few minutes using mostly copy-paste commands.  They will take you through:
+
+    - Setting up the initial config file
+    - Creating some sample collections using the defaults
+    - Setting up a collection file and creating a sample collection
+    - Adding some default overlays
+
+After you complete the steps in one of those walkthroughs, you will have a working Kometa setup, ready for you to tune and expand.
+
+### Those walkthroughs don't cover my NAS
+
+That same config file can be used on any platform or NAS; you don't need to create a new one for each platform.
+
+The walkthrough can be completed on any platform, regardless of where you plan to run Kometa.  For example, if you plan to run Kometa on a NAS like a Synology or what have you, you can complete the walkthrough on your Windows or MacOS system, and then copy the config file to the NAS.  You may need to adjust a path or two in the config file, and perhaps change the Plex/Radarr/Sonarr/Tautulli URLs if they need to be addressed differently from a container on the NAS, but otherwise the config file is portable.
+
+Docker is Docker, and conceptually the same [at this level] on any platform.  If you are using the docker command line, the commands to pull the image and run the container are the same on any platform.  The only difference is the path to the config file, which you will need to adjust.
+
+The GUI for creating a docker container will differ from NAS to NAS, and there's no way for this documentation to cover any and all variations, but the basic steps are the same:
+
+1. create container from the official image
+2. map a local directory to the container at `/config`
+3. put a `config.yml` file in that directory
+
+Those steps are the same on any platform, though the things you need click may vary.  Any NAS that can run a docker container can do those three things; none of them are unique to Kometa.
+
+## There's so much in this config file
+
+There is.  Kometa is a powerful tool with a lot of features.  But you don't need to understand all of them to get started.  You can start with a simple config file and build up from there.
+
+The absolute minimum config file is just a few lines.  You can add more features as you learn about them and as you need them.
+
+### Minimal `config.yml`
+
+Here's the absolute minimum `config.yml` file you need to get started:
+
+```yaml
+libraries:
+  NAME_OF_YOUR_MOVIE_LIBRARY
+    collection_files:
+      - default: basic
+ 
+plex:
+  url: YOUR_PLEX_URL
+  token: YOUR_PLEX_TOKEN
+
+tmdb:
+  apikey: YOUR_TMDB_API_KEY
+```
+
+Change those four UPPER_CASE items to your actual values, and you're good to go.  Running that file will create a couple of collections in your Plex library.
+
+Kometa will *also* fill in that file with a lot of defaults, ready for you to modify and expand as you learn more about Kometa.  It does this so that as new settings are added, the default values are inserted into your config file, ready for you to modify.
+
+Once you have Kometa set up and are actively making changes, most of your changes will happen under the `libraries` section of the config file.  *Most*.  **Not** "all", **most**.  There are of course changes you can and may want to do elsewhere to support your requirements, but the vast majority of your work will be in the `libraries` section.
+
+## Start slow and build up
+
+The single most common mistake most new users make is trying to add everything at once.  They see the power of Kometa and want to use all of it right away.  This is a recipe for frustration.
+
+Start slow.  Start simple.  Add a feature or two at a time.  Learn how they work.  Understand how they interact with each other.  Then add more features.
+
+There's a config floating around from bullmoose20 that a lot of people decide to start with.  You don't need to start with that.  You *SHOULDN'T* start with that.  That config will take hours if not days to run on nearly any system against nearly any library.  It's a complex config that is meant to show off the power of Kometa, not to be a starting point.
+
+You can start with the minimal config above and build up from there.
+
+Another common mistake is finding some config on Reddit or elsewhere and just copy-pasting the whole thing, or worse, chunks of the whole thing, into your config file.  This is a recipe for disaster.  Probably, you don't know what all those settings do, and you don't know how they interact with each other.  Then you're going to search for things in the wiki and find stuff out of context, copy-paste *those* things, and still have problems.  You're going to have a bad time.
+
+I know it's boring and you want the cool stuff now, but trust me.  Start slow.  Start simple.  Build up from there.
+
+Kometa is, for better or worse, a very technical tool and requires a certain amount of technical knowledge to use.  You don't need to be a programmer, but you do need to be able to read and understand the documentation, and you do need to be able to understand how the tool works.
+
+## Next steps
+
+So you have a working config file.  What now?
+
+## Defaults
+
+Perhaps you want to explore the collections and overlays that Kometa provides as part of the defaults.  If you want to create a variety of collections with a minimum of fuss, these are for you.  They can be enabled in your config with a single line, and support limited customization via "template_variables" in the config file.
+
+For example, this will create 7 Academy Award collections, "Best Picture" (all years), "Best Director" (all years), and yearly collections for the past five years.
+
+```yaml
+libraries:
+  Movies:
+    collection_files:
+      - default: oscars
+```
+
+If you wanted to create yearly collections for the past ten years, you could do that with:
+
+```yaml
+libraries:
+  Movies:
+    collection_files:
+      - default: oscars
+        template_variables:
+          data:
+           starting: latest-11
+```
+
+All of the defaults work this way.  You can enable them with a single line, and customize them with `template_variables`.
+
+The defaults are all documented starting [here](../../defaults/guide.md).
+
+## Custom Collections/Overlays/Metadata
+
+If the defaults don't meet your needs, you can create your own external YAML files to define your own collections, overlays, and metadata.  These files can be as simple or as complex as you need them to be.
+
+The various types of external YAML files are discussed starting [here](../install/files.md).
+
+## Community configs
+
+There are a variety of configs supplied by the community in the community configs repo.
+
+IMPORTANT: These configs are not supported by the Kometa team.  They are provided by the community, and you should use them at your own risk.  They are not guaranteed to work, and they may not be up to date with the latest changes in Kometa.
+
+You can find the community configs [here](https://github.com/Kometa-Team/Community-Configs).  When you visit, note that the last modified dates on most of them are **years** ago.  They may not work with the current version of Kometa.

docs/kometa/install/local.md

@@ -5,7 +5,9 @@ This article will walk you through getting Kometa set up and running.  It will c
 1. Retrieving the Kometa code
 2. Installing requirements
 3. Setting up the initial config file
-4.  Setting up a collection file and creating a couple sample collections.
+4. Creating some sample collections using the defaults
+5. Setting up a collection file and creating a sample collection.
+6. Adding some default overlays.
 
 The specific steps you will be taking:
 
@@ -14,12 +16,12 @@ The specific steps you will be taking:
 3. Use `git` to retrieve the code
 4. Install requirements [extra bits of code required for Kometa]
 5. Gather two things that the script requires:
-    1. TMDb API Key
+   - TMDb API Key
-    2. Plex URL and Token
+   - Plex URL and Token
 
 6. Then, iteratively:
-    1. use `python` to run the script
+   - use `python` to run the script
-    2. use a text editor to modify a couple of text files until you have a working config file and a single working collection file.
+   - use a text editor to modify a couple of text files until you have a working config file and a single working collection file.
 
 Note that running a Python script is inherently a pretty technical process.  If you are unable or unwilling to learn the rudiments of using tools like python and git, you should probably strongly consider running Kometa in [Docker](docker.md).  That will eliminate the Python and git installs from this process and make it as simple as it can be.
 
@@ -31,7 +33,7 @@ Finally, this walkthrough is intended to give you a basic grounding in how to ge
 
 Nearly anywhere you see
 
-```
+```txt
 something like this
 ```
 

mkdocs.yml

@@ -133,6 +133,7 @@ nav:
       - INSTALLATION:
         - Installing Kometa: kometa/install/overview.md
         - Docker Images: kometa/install/images.md
+        - Getting Start: kometa/install/getting_started.md
         - Configuring Kometa: kometa/install/files.md
         - Walkthroughs:
           - Local (Win/Mac/Linux): kometa/install/local.md