From b4b72e3b73d7f180b8decd248951e9e62549f869 Mon Sep 17 00:00:00 2001
From: Jan Henckens <jan@henckens.be>
Date: Thu, 22 Feb 2024 19:59:48 +0100
Subject: [PATCH] Docs

---
 docs/console.md            | 33 ++++++++++++++++++++++++++++
 docs/events.md             | 45 ++++++++++++++++++++++++++++++++++++++
 docs/replicas.md           | 29 ++++++++++++++++++++++++
 docs/splitting-elements.md | 17 ++++++++++++++
 4 files changed, 124 insertions(+)
 create mode 100644 docs/console.md
 create mode 100644 docs/replicas.md
 create mode 100644 docs/splitting-elements.md

diff --git a/docs/console.md b/docs/console.md
new file mode 100644
index 0000000..96a34b6
--- /dev/null
+++ b/docs/console.md
@@ -0,0 +1,33 @@
+---
+title: Console commands
+---
+# Console commands
+
+Scout provides two easy console commands for managing your indices.
+
+### Importing
+To import one or all indices you can run the following console command
+
+```
+./craft scout/index/import <indexName?>
+```
+
+The `indexName` argument is not required, all your mappings will be imported when you omit it.
+
+### Flushing/Clearing
+Clearing an index is as easy as running a command in your console.
+
+```
+./craft scout/index/flush <indexName?>
+```
+
+As with the import command, `indexName` is not required.
+
+When flushing, Scout will ask you to confirm that you really want to clear all the data in your index. You can bypass the confirmation by appending a `--force` flag.
+
+### Refreshing
+Does a flush/clear first and then imports the index again.
+
+```
+./craft scout/index/refresh <indexName?>
+```
\ No newline at end of file
diff --git a/docs/events.md b/docs/events.md
index 059d522..7da5d26 100644
--- a/docs/events.md
+++ b/docs/events.md
@@ -2,3 +2,48 @@
 title: Events
 ---
 # Events
+
+## ShouldBeSearchableEvent
+
+This event allows you to customize which elements or element types get checked on save (or more specifically, every time the `SearchableBehaviour` is triggered).
+
+```php 
+
+use rias\scout\behaviors\SearchableBehavior;
+use rias\scout\events\ShouldBeSearchableEvent;
+
+Event::on(
+    SearchableBehavior::class, 
+    SearchableBehavior::EVENT_SHOULD_BE_SEARCHABLE, 
+    function (ShouldBeSearchableEvent $event) {
+        $event->shouldBeSearchable = false;
+});
+```
+
+The event has a properties:
+- $element (the element being saved)
+- $shouldBeSearchable (wether or not the element should be searchable, defaults to `true`)
+
+An example use-case for this would be to check the type of the element that's being saved and settings `shouldBeSearchable` to `false` when it's a Matrix block.
+
+## AfterIndexImport
+
+This event runs at the end of the `ImportIndex` job, when every item has been processed.
+
+```php 
+
+use rias\scout\events\AfterIndexImport;
+use rias\scout\jobs\ImportIndex;
+
+Event::on(
+    ImportIndex::class,
+    ImportIndex::EVENT_AFTER_INDEX_IMPORT,
+    function (AfterIndexImport $event) {
+        // Your code here
+    });
+```
+
+The event has one property:
+- $indexName (the name of the index that just finished importing
+
+An example use-case for this would be to keep a log or dateLastImported if you're running imports on a schedule.
diff --git a/docs/replicas.md b/docs/replicas.md
new file mode 100644
index 0000000..3de1bb4
--- /dev/null
+++ b/docs/replicas.md
@@ -0,0 +1,29 @@
+---
+title: Replicas
+---
+# Replicas
+
+Replicas can be created with the `replicas` function on `IndexSettings`. To configure replicas, include them in the `indices` array and set their `replicaIndex` to `true` so that they are not included in any syncing operations.
+
+Replica indices can have their configuration updated using the `./craft scout/settings/update` console command.
+
+```php
+<?php
+
+return [
+    'indices' => [
+        \rias\scout\ScoutIndex::create('Products')
+            // ...
+            ->indexSettings(
+                \rias\scout\IndexSettings::create()
+                    ->minWordSizefor1Typo(4)
+                    ->replicas(['virtual(Products_desc)'])
+            )
+    ],
+    [
+        \rias\scout\ScoutIndex::create('Products_desc')
+            ->replicaIndex(true)
+            ->indexSettings(IndexSettings::create()->customRanking(['desc(price)'])),
+    ],
+];
+```
\ No newline at end of file
diff --git a/docs/splitting-elements.md b/docs/splitting-elements.md
new file mode 100644
index 0000000..2bffa74
--- /dev/null
+++ b/docs/splitting-elements.md
@@ -0,0 +1,17 @@
+---
+title: Events
+---
+# Events
+
+[For long documents](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/indexing-long-documents/) it is advised to divide the element into multiple rows to keep each row within row data size. This can be done using `splitElementsOn()`.
+> Make sure to return an array in your transformer for these keys.
+
+```php
+->splitElementsOn([
+    'summary',
+    'matrixFieldHandle'
+])
+```
+::: warning *Important*
+`distinctID` (available after indexing) must be set up as an attribute for faceting for deletion of objects to work when using splitElementsOn.
+:::