rename docs

13 files changed, 288 insertions, 308 deletions

diff --git a/README.md b/README.md
index f164c72..75cffd4 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 <p align="center">
- <img width="623" height="168" src="https://github.com/tfeldmann/organize/raw/master/docs/img/organize.svg?sanitize=true" alt="organize logo">
+  <img width="623" height="168" src="https://github.com/tfeldmann/organize/raw/master/docs/img/organize.svg?sanitize=true" alt="organize logo">
 </p>
 
 <div align="center">
diff --git a/docs/01-config.md b/docs/01-config.md
deleted file mode 100644
index ba78b77..0000000
--- a/docs/01-config.md
+++ /dev/null
@@ -1,296 +0,0 @@
-# Configuration
-
-## Editing the configuration
-
-organize has a default config file if no other file is given.
-
-To edit the default configuration file:
-
-```sh
-$ organize edit  # opens in $EDITOR
-$ organize edit --editor=vim
-$ EDITOR=code organize edit
-```
-
-To open the folder containing the configuration file:
-
-```sh
-$ organize reveal
-$ organize reveal --path  # show the full path to the default config
-```
-
-To debug your configuration run:
-
-```sh
-$ organize check
-```
-
-## Configuration basics
-
-## Environment variables
-
-- `EDITOR` - The editor used to edit the config file.
-- `ORGANIZE_CONFIG` - The path to the default config file.
-- `NO_COLOR` - if this is set, the output is not colored.
-
-## Rule syntax
-
-The rule configuration is done in [YAML](https://learnxinyminutes.com/docs/yaml/).
-You need a top-level element `rules` which contains a list of rules.
-Each rule defines `folders`, `filters` (optional) and `actions`.
-
-```yaml
-rules:
-- folders:
-    - ~/Desktop
-    - /some/folder/
-  filters:
-    - lastmodified:
-        days: 40
-        mode: newer - extension: pdf
-  actions:
-    - move: ~/Desktop/Target/ - trash
-
-  - folders:
-    - ~/Inbox
-    filters:
-      - extension: pdf
-    actions:
-      - move: ~/otherinbox
-```
-
-- `folders` is a list of folders you want to organize.
-- `filters` is a list of filters to apply to the files - you can filter by file extension, last modified date, regular expressions and many more. See :ref:`Filters`.
-- `actions` is a list of actions to apply to the filtered files. You can put them into the trash, move them into another folder and many more. See :ref:`Actions`.
-
-Other optional per rule settings:
-
-- `enabled` can be used to temporarily disable single rules. Default = true
-- `subfolders` specifies whether subfolders should be included in the search. Default = false. This setting only applies to folders without glob wildcards.
-- `system_files` specifies whether to include system files (desktop.ini, thumbs.db, .DS_Store) in the search. Default = false
-
-## Folder syntax
-
-Every rule in your configuration file needs to know the folders it applies to.
-The easiest way is to define the rules like this:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - /path/one - /path/two
-filters: ...
-actions: ...
-
-    - folders:
-        - /path/one
-        - /another/path
-      filters: ...
-      actions: ...
-
-.. note::
-
-- You can use environment variables in your folder names. On windows this means you can use `%public%/Desktop`, `%APPDATA%`, `%PROGRAMDATA%` etc.
-
-### Globstrings
-
-You can use globstrings in the folder lists. For example to get all files with filenames ending with `_ui` and any file extension you can use:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - '~/Downloads/_\_ui._'
-actions: - echo: '{path}'
-
-You can use globstrings to recurse through subdirectories (alternatively you can use the `subfolders: true` setting as shown below)
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - '~/Downloads/\*_/_.\*'
-actions: - echo: 'base {basedir}, path {path}, relative: {relative_path}'
-
-    # alternative syntax
-    - folders:
-        - ~/Downloads
-      subfolders: true
-      actions:
-        - echo: 'base {basedir}, path {path}, relative: {relative_path}'
-
-The following example recurses through all subdirectories in your downloads folder and finds files with ending in `.c` and `.h`.
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - '~/Downloads/\*_/_.[c|h]'
-actions: - echo: '{path}'
-
-.. note::
-
-- You have to target files with the globstring, not folders. So to scan through all folders starting with \_log\__ you would write `yourpath/log\_\_/_`
-
-### Excluding files and folders
-
-Files and folders can be excluded by prepending an exclamation mark. The following example selects all files
-in `~/Downloads` and its subfolders - excluding the folder `Software`:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - '~/Downloads/\*_/_' - '! ~/Downloads/Software'
-actions: - echo: '{path}'
-
-Globstrings can be used to exclude only specific files / folders. This example:
-
-- adds all files in `~/Downloads`
-- exludes files from that list whose name contains the word `system` ending in `.bak`
-- adds all files from `~/Documents`
-- excludes the file `~/Documents/important.txt`.
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: - '~/Downloads/**/\*' - '! ~/Downloads/**/_system_.bak' - '~/Documents' - '! ~/Documents/important.txt'
-actions: - echo: '{path}'
-
-.. note::
-
-- Files and folders are included and excluded in the order you specify them!
-- Please make sure your are putting the exclamation mark within quotation marks.
-
-### Aliases
-
-Instead of repeating the same folders in each and every rule you can use an alias for multiple folders which you can then reference in each rule.
-Aliases are a standard feature of the YAML syntax.
-
-.. code-block:: yaml
-:caption: config.yaml
-
-all_my_messy_folders: &all - ~/Desktop - ~/Downloads - ~/Documents - ~/Dropbox
-
-rules: - folders: \*all
-filters: ...
-actions: ...
-
-    - folders: *all
-      filters: ...
-      actions: ...
-
-You can even use multiple folder lists:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-private_folders: &private - '/path/private' - '~/path/private'
-
-work_folders: &work - '/path/work' - '~/My work folder'
-
-all_folders: &all - *private - *work
-
-rules: - folders: \*private
-filters: ...
-actions: ...
-
-    - folders: *work
-      filters: ...
-      actions: ...
-
-    - folders: *all
-      filters: ...
-      actions: ...
-
-    # same as *all
-    - folders:
-        - *work
-        - *private
-      filters: ...
-      actions: ...
-
-## Filter syntax
-
-`filters` is a list of :ref:`Filters`.
-Filters are defined like this:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: ...
-actions: ...
-filters: # filter without parameters - FilterName
-
-        # filter with a single parameter
-        - FilterName: parameter
-
-        # filter expecting a list as parameter
-        - FilterName:
-          - first
-          - second
-          - third
-
-        # filter with multiple parameters
-        - FilterName:
-            parameter1: true
-            option2: 10.51
-            third_argument: test string
-
-.. note::
-Every filter comes with multiple usage examples which should be easy to adapt for your use case!
-
-## Action syntax
-
-`actions` is a list of :ref:`Actions`.
-Actions can be defined like this:
-
-.. code-block:: yaml
-:caption: config.yaml
-
-rules: - folders: ...
-actions: # action without parameters - ActionName
-
-        # action with a single parameter
-        - ActionName: parameter
-
-        # filter with multiple parameters
-        - ActionName:
-            parameter1: true
-            option2: 10.51
-            third_argument: test string
-
-.. note::
-Every action comes with multiple usage examples which should be easy to adapt for your use case!
-
-### Variable substitution (placeholders)
-
-**You can use placeholder variables in your actions.**
-
-Placeholder variables are used with curly braces `{var}`.
-You always have access to the variables `{path}`, `{basedir}` and `{relative_path}`:
-
-- `{path}` -- is the full path to the current file
-- `{basedir}` -- the current base folder (the base folder is the folder you
-  specify in your configuration).
-- `{relative_path}` -- the relative path from `{basedir}` to `{path}`
-
-Use the dot notation to access properties of `{path}`, `{basedir}` and `{relative_path}`:
-
-- `{path}` -- the full path to the current file
-- `{path.name}` -- the full filename including extension
-- `{path.stem}` -- just the file name without extension
-- `{path.suffix}` -- the file extension
-- `{path.parent}` -- the parent folder of the current file
-- `{path.parent.parent}` -- parent calls are chainable...
-
-- `{basedir}` -- the full path to the current base folder
-- `{basedir.parent}` -- the full path to the base folder's parent
-
-and any other property of the python `pathlib.Path` (`official documentation <https://docs.python.org/3/library/pathlib.html#methods-and-properties>`\_) object.
-
-Additionally :ref:`Filters` may emit placeholder variables when applied to a
-path. Check the documentation and examples of the filter to see available
-placeholder variables and usage examples.
-
-Some examples include:
-
-- `{lastmodified.year}` -- the year the file was last modified
-- `{regex.yournamedgroup}` -- anything you can extract via regular expressions
-- `{extension.upper}` -- the file extension in uppercase
-- ... and many more.
diff --git a/docs/02-locations.md b/docs/02-locations.md
deleted file mode 100644
index b7a7f0d..0000000
--- a/docs/02-locations.md
+++ /dev/null
@@ -1 +0,0 @@
-# Locations
diff --git a/docs/04-actions.md b/docs/actions.md
index e3ab74f..125f814 100644
--- a/docs/04-actions.md
+++ b/docs/actions.md
@@ -22,7 +22,7 @@ rules:
       - duplicate
       - name
     actions:
-      - confirm: "Delete {name}?"
+      - confirm: "Delete {duplicate}?"
       - trash
 ```
 
diff --git a/docs/05-changelog.md b/docs/changelog.md
index 15fe40c..15fe40c 100644
--- a/docs/05-changelog.md
+++ b/docs/changelog.md
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..b20ccc8
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,55 @@
+# Configuration
+
+## Editing the configuration
+
+organize has a default config file if no other file is given.
+
+To edit the default configuration file:
+
+```sh
+$ organize edit  # opens in $EDITOR
+$ organize edit --editor=vim
+$ EDITOR=code organize edit
+```
+
+To open the folder containing the configuration file:
+
+```sh
+$ organize reveal
+$ organize reveal --path  # show the full path to the default config
+```
+
+To check your configuration run:
+
+```sh
+$ organize check
+$ organize check --debug  # check with debug output
+```
+
+## Running and simulating
+
+To run / simulate the default config file:
+
+```sh
+$ organize sim
+$ organize run
+```
+
+To run / simulate a specific config file:
+
+```sh
+$ organize sim [FILE]
+$ organize run [FILE]
+```
+
+## Environment variables
+
+- `ORGANIZE_CONFIG` - The path to the default config file.
+- `NO_COLOR` - if this is set, the output is not colored.
+- `EDITOR` - The editor used to edit the config file.
+
+## Command line interface
+
+::: mkdocs-click
+    :module: organize.cli
+    :command: organize
diff --git a/docs/03-filters.md b/docs/filters.md
index a71106c..1484c29 100644
--- a/docs/03-filters.md
+++ b/docs/filters.md
@@ -1,7 +1,7 @@
 # Filters
 
 This page shows the specifics of each filter. For basic filter usage and options have a
-look at the [Config](01-config.md) section.
+look at the [Configuration](00-configuration.md) section.
 
 ## created
 
diff --git a/docs/index.md b/docs/index.md
index d064e03..8dc9557 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,4 +1,4 @@
-# Welcome to the documentation for organize
+# Welcome to organize's documentation
 
 {%
    include-markdown "../README.md"
diff --git a/docs/locations.md b/docs/locations.md
new file mode 100644
index 0000000..8811dc4
--- /dev/null
+++ b/docs/locations.md
@@ -0,0 +1,82 @@
+# Locations
+
+**Locations** are the folders in which organize searches for resources.
+You can set multiple locations for each rule if you want.
+
+A minimum location definition is just a path where to look for files / folders:
+
+```yml
+rules:
+  - name: "Single location"
+    locations: ~/Desktop
+    actions: ...
+```
+
+If you want to handle multiple locations in a rule, create a list:
+
+```yaml
+rules:
+  - name: "Location list"
+    locations:
+      - ~/Desktop
+      - /usr/bin/
+      - "%PROGRAMDATA%/test"
+    actions: ...
+```
+
+Using options:
+
+```yaml
+rules:
+  - name: "Location list"
+    locations:
+      - path: "~/Desktop"
+        max_depth: 3
+    actions: ...
+```
+
+Note that you can use environment variables in your locations.
+
+## Location options
+
+```yaml
+rules:
+  - locations:
+      path: ...
+      max_depth: ...
+      search: ...
+      exclude_files: ...
+      exclude_dirs: ...
+      system_exlude_files: ...
+      system_exclude_dirs: ...
+      ignore_errors: ...
+      filter: ...
+      filter_dirs: ...
+      filesystem: ...
+```
+
+- **path** (`str`):
+- **max_depth** (`int` or `null`):
+- **search** (`str`): "depth", "breadth")):
+- **exclude_files** (list of `str`):
+- **exclude_dirs** (list of `str`):
+- **system_exlude_files** (list of `str`):
+- **system_exclude_dirs** (list of `str`):
+- **ignore_errors** (`bool`):
+- **filter** (list of `str`):
+- **filter_dirs** (list of `str`):
+- **filesystem** (str):
+
+### `filesystem` and `path`
+
+
+
+## Relative locations
+
+## Filesystems
+
+      actions: ...
+
+.. note::
+
+- You can use environment variables in your folder names. On windows this means you can use `%public%/Desktop`, `%APPDATA%`, `%PROGRAMDATA%` etc.
diff --git a/docs/rules.md b/docs/rules.md
new file mode 100644
index 0000000..c4d7f06
--- /dev/null
+++ b/docs/rules.md
@@ -0,0 +1,139 @@
+# Rules
+
+A organize config file can be written in [YAML](https://learnxinyminutes.com/docs/yaml/)
+or [JSON](https://learnxinyminutes.com/docs/json/). See [configuration](00-configuration.md)
+on how to locate your config file.
+
+The top level element must be a dict with a key "rules".
+"rules" contains a list of objects with the required keys "locations" and "actions".
+
+A minimum config:
+
+```yaml
+rules:
+  - locations: "~/some/location"
+    actions:
+      - echo: "Hello World!"
+```
+
+Organize checks your rules from top to bottom. For every resource in each location (top to bottom)
+it will check whether the filters apply (top to bottom) and then execute the given actions (top to bottom).
+
+So with this minimal configuration it will print "Hello World!" for each file it finds in `"~/some/location"`.
+
+## Rule options
+
+```yaml
+rules:
+  # First rule
+  - name: ...
+    enabled: ...
+    targets: ...
+    locations: ...
+    subfolders: ...
+    filter_mode: ...
+    filters: ...
+    actions: ...
+
+  # Another rule
+  - name: ...
+    enabled: ...
+    # ... and so on
+```
+
+The rule options in detail:
+
+- **name** (`str`): The rule name
+- **enabled** (`bool`): Whether the rule is enabled / disabled _(Default: `true`)_
+- **targets** (`str`): `"dirs"` or `"files"` _(Default: `"files"`)_
+- **locations** (`str`|`list`) - A single location string or list of [locations](02-locations.md)
+- **subfolders** (`bool`): Whether to recurse into subfolders of all locations _(Default: `false`)_
+- **filter_mode** (`str`): `"all"`, `"any"` or `"none"` of the filters must apply _(Default: `"all"`)_
+- **filters** (`list`): A list of [filters](03-filters.md) _(Default: `[]`)_
+- **actions** (`list`): A list of [actions](04-actions.md)
+
+## Templates and placeholders
+
+**You can use placeholder variables in your actions.**
+
+Placeholder variables are used with curly braces `{var}`.
+You always have access to the variables `{path}`, `{basedir}` and `{relative_path}`:
+
+- `{path}` -- is the full path to the current file
+- `{basedir}` -- the current base folder (the base folder is the folder you
+  specify in your configuration).
+- `{relative_path}` -- the relative path from `{basedir}` to `{path}`
+
+Use the dot notation to access properties of `{path}`, `{basedir}` and `{relative_path}`:
+
+- `{path}` -- the full path to the current file
+- `{path.name}` -- the full filename including extension
+- `{path.stem}` -- just the file name without extension
+- `{path.suffix}` -- the file extension
+- `{path.parent}` -- the parent folder of the current file
+- `{path.parent.parent}` -- parent calls are chainable...
+
+- `{basedir}` -- the full path to the current base folder
+- `{basedir.parent}` -- the full path to the base folder's parent
+
+and any other property of the python `pathlib.Path` (`official documentation <https://docs.python.org/3/library/pathlib.html#methods-and-properties>`\_) object.
+
+Additionally :ref:`Filters` may emit placeholder variables when applied to a
+path. Check the documentation and examples of the filter to see available
+placeholder variables and usage examples.
+
+Some examples include:
+
+- `{lastmodified.year}` -- the year the file was last modified
+- `{regex.yournamedgroup}` -- anything you can extract via regular expressions
+- `{extension.upper}` -- the file extension in uppercase
+- ... and many more.
+
+
+## Advanced: Aliases
+
+Instead of repeating the same folders in each and every rule you can use an alias for multiple folders which you can then reference in each rule.
+Aliases are a standard feature of the YAML syntax.
+
+.. code-block:: yaml
+:caption: config.yaml
+
+all_my_messy_folders: &all - ~/Desktop - ~/Downloads - ~/Documents - ~/Dropbox
+
+rules: - folders: \*all
+filters: ...
+actions: ...
+
+    - folders: *all
+      filters: ...
+      actions: ...
+
+You can even use multiple folder lists:
+
+.. code-block:: yaml
+:caption: config.yaml
+
+private_folders: &private - '/path/private' - '~/path/private'
+
+work_folders: &work - '/path/work' - '~/My work folder'
+
+all_folders: &all - *private - *work
+
+rules: - folders: \*private
+filters: ...
+actions: ...
+
+    - folders: *work
+      filters: ...
+      actions: ...
+
+    - folders: *all
+      filters: ...
+      actions: ...
+
+    # same as *all
+    - folders:
+        - *work
+        - *private
+      filters: ...
+      actions: ...
diff --git a/docs/06-updating-from-v1.md b/docs/updating-from-v1.md
index bbdd2f1..bbdd2f1 100644
--- a/docs/06-updating-from-v1.md
+++ b/docs/updating-from-v1.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 05e7d44..b710ee9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -3,12 +3,13 @@ repo_url: https://github.com/tfeldmann/organize/
 site_author: "Thomas Feldmann"
 nav:
   - Home: index.md
-  - Configuration: 01-config.md
-  - Locations: 02-locations.md
-  - Filters: 03-filters.md
-  - Actions: 04-actions.md
-  - Changelog: 05-changelog.md
-  - Updating from organize v1.x: 06-updating-from-v1.md
+  - Configuration: configuration.md
+  - Rules: rules.md
+  - Locations: locations.md
+  - Filters: filters.md
+  - Actions: actions.md
+  - Changelog: changelog.md
+  - Updating from organize v1.x: updating-from-v1.md
 plugins:
   - search
   - include-markdown
@@ -31,6 +32,7 @@ plugins:
 markdown_extensions:
   - toc:
       permalink: "#"
+  - mkdocs-click
 
 theme:
   name: readthedocs
diff --git a/organize/config.py b/organize/config.py
index ba54a7e..aac7835 100644
--- a/organize/config.py
+++ b/organize/config.py
@@ -47,7 +47,6 @@ CONFIG_SCHEMA = Schema(
                 "actions": [Optional(x.get_schema()) for x in ACTIONS.values()],
             },
         ],
-        Optional("version"): int,
     },
     name="organize rule configuration",
 )