Documentation the extensions functionalities

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`.

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

doorstop/core/tests/validators/validator_dummy.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: LGPL-3.0-only
+
 from doorstop import DoorstopError, DoorstopInfo, DoorstopWarning
 
 

reqs/ext/.req_sha_item_validator.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: LGPL-3.0-only
 from doorstop import DoorstopInfo, DoorstopWarning, DoorstopError
 from subprocess import check_output
 from copy import copy