From 7a66b22eff8c0eb322c8b2414dbeb9cc7b1d3fa4 Mon Sep 17 00:00:00 2001
From: Lucas Biaggi <lucas.biaggi@codethink.co.uk>
Date: Mon, 22 Jan 2024 15:45:51 +0000
Subject: [PATCH] Documentation the extensions functionalities

---
 docs/api/scripting.md  | 36 +++++++++++++++++++++++++++++++++
 docs/reference/item.md | 45 ++++++++++++++++++++++++++++++++++++++----
 2 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/docs/api/scripting.md b/docs/api/scripting.md
index 1baebf16d..16fc4fd58 100644
--- a/docs/api/scripting.md
+++ b/docs/api/scripting.md
@@ -73,3 +73,39 @@ if __name__ == '__main__':
 ```
 
 Both `document_hook` and `item_hook` are optional, but if provided these callbacks will be passed each corresponding instance. Each callback should yield instances of Doorstop's exception classes based on severity of the issue.
+
+## Validation Hook per folder
+
+Doorstop also has an extension which allows creating an item validation per folder, allowing the document to have different validations for each document section.
+To enable this mechanism you must insert into your `.doorstop.yml` file the following lines:
+
+```yaml
+extensions:
+  item_validator: .req_sha_item_validator.py # a python file path relative to .doorstop.yml
+```
+
+or
+
+```yaml
+extensions:
+  item_validator: ../validators/my_complex_validator.py # a python file path relative to .doorstop.yml
+```
+
+The referenced file must have a function called `item_validator` with a single parameter `item`.
+
+Example:
+
+```python
+
+
+def item_validator(item):
+    if getattr(item, "references") == None:
+        return [] # early return
+    for ref in item.references:
+        if ref['sha'] != item._hash_reference(ref['path']):
+            yield DoorstopError("Hash has changed and it was not reviewed properly")
+
+```
+
+Although it is not required, it is recommended to yield a Doorstop type such as,
+`DoorstopInfo`, `DoorstopError`, or `DoorstopWarning`.
diff --git a/docs/reference/item.md b/docs/reference/item.md
index adb6b5c88..5f5a79e2e 100644
--- a/docs/reference/item.md
+++ b/docs/reference/item.md
@@ -243,10 +243,47 @@ of the item.
 
 ```yaml
 references:
-- path: tests/test1.cpp
-  type: file
-- path: tests/test2.cpp
-  type: file
+  - path: tests/test1.cpp
+    type: file
+  - path: tests/test2.cpp
+    type: file
+```
+
+### Generating hash for referenced files
+
+Doorstop has an extension to generate a hash for each referenced file inside the array.
+
+.doorstop.yml
+
+```yaml
+settings:
+  digits: 3
+  prefix: REQ
+  sep: ""
+extensions:
+  item_sha_required: true
+```
+
+Now when reviewing items, Doorstop will insert a field named `sha` where each item reference will
+contain a `sha256`.
+
+Example:
+
+```yaml
+active: true
+derived: false
+header: ""
+level: 2.0
+links: []
+normative: true
+ref: ""
+references:
+  - path: files/a.file
+    sha: 28c16553011a46bca9b78d189f8fd30c59c4138a1b6a9a4961f525849d48037e
+    type: file
+reviewed: BU95pdUUcz5DrFur8GUUqBaIXSNPBYMEZVMy-6IPM4s=
+text: |
+  My text
 ```
 
 ### Note: new behavior vs old behavior