[Bf-blender-cvs] [7aac6ef98a9] shot-tools-development: Merge branch 'shot-tools-development' of git.blender.org:blender-studio-tools into shot-tools-development

[Jeroen Bakker]

Commit: 7aac6ef98a9c607c7e573bc4fa1fb40b080a71b1
Author: Jeroen Bakker
Date:   Wed Dec 9 14:49:38 2020 +0100
Branches: shot-tools-development
https://developer.blender.org/rB7aac6ef98a9c607c7e573bc4fa1fb40b080a71b1

Merge branch 'shot-tools-development' of git.blender.org:blender-studio-tools into shot-tools-development

===================================================================



===================================================================

diff --cc shot-tools/README.md
index 308cf433eb1,e27ed08951d..343754ab6c2
--- a/shot-tools/README.md
+++ b/shot-tools/README.md
@@@ -1,6 -1,6 +1,6 @@@
 -# Project Description
 +# Project Description (DRAFT)
  
- Shot tools is an Add-on that helps studios to work with task specific 
+ Shot Tools is an Add-on that helps studios to work with task specific
  blend-files. The main functionalities are
  
  * Build blend files for a specific task and shot.
@@@ -29,9 -29,9 +29,9 @@@ systems. The connectors will add flexib
  in multiple productions or studios.
  
  In the configuration files the TD can setup the connectors that are use for
 -the production. There are several connectors in the add-on:
 +the production. Possible connectors would be:
  
- * Connector for text based config files (json/yaml). 
+ * Connector for text based config files (json/yaml).
  * Connector for kitsu (https://www.cg-wire.com/en/kitsu.html).
  * Connector for blend files.
  
@@@ -63,73 -63,12 +63,73 @@@ def hook_task_anim(task: shot_tools.Tas
      """
  ```
  
 +### Data
 +
 +All hooks will must have pythons `**kwargs` parameter. The `kwargs` contains
 +the context at the moment the hook is invoked. The context can contain the
 +following items.
 +
 +* `production`: `shot_tools.Production`: Include the name of the production
 +  and the location on the filesystem.
 +* `task`: `shot_tools.Task`: The task (combination of task_type and shot)
 +* `task_type`: `shot_tools.TaskType`: Is part of the `task`.
 +* `sequence`: `shot_tools.Sequence`: Is part of `shot`.
 +* `shot`: `shot_tools.Shot` Is part of `task`.
 +* `asset`: `shot_tools.Asset`: Only available during asset loading phase.
 +* `asset_type`: `shot_tools.AssetType`: Only available during asset loading phase.
 +
 +### Execution Order
 +
  The add-on will internally create a list containing the hooks that needs to be
- executed for the command in the order what will make sense. It will then
- execute them one by one.
+ executed for the command in a sensible order. It will then execute them in that
+ order.
  
 -A hook can request/use needed data by simply adding a parameter. The `**kwargs`
 -will contain data that cannot be mapped to a parameter.
 +By default the next order will be used:
 +
 +* Production wide hooks
 +* Asset hooks
 +* Asset Type hooks
 +* Sequence hooks
 +* Shot hooks
 +* Task type hooks
 +
 +When a hook needs is defined to match an asset it will always be run when during
 +the asset loading phase.
 +
 +#### Events
 +
 +When order of execution can be customized by adding the optional `run_before`
 +or `run_after` parameters.
 +
 +```
 + at shot_tools.hook(match_task_type='anim',
 +                 run_after=[shot_tools.events.AssetsLoaded()],
 +                 run_before=[shot_tools.events.ShotOverrides()])
 +def hook_task_anim(task: shot_tools.Task, shot: shot_tools.Shot, **kwargs) -> None:
 +    """
 +    Specific overrides for any animation task run after all assets have been loaded.
 +    """
 +```
 +
 +Events could be:
 +
 +* `shot_tools.events.BuildStart`
 +* `shot_tools.events.ProductionSettingsLoaded`
 +* `shot_tools.events.AssetsLoaded`
 +* `shot_tools.events.AssetTypeOverrides`
 +* `shot_tools.events.SequenceOverrides`
 +* `shot_tools.events.ShotOverrides`
 +* `shot_tools.events.TaskTypeOverrides`
 +* `shot_tools.events.BuildFinished`
 +* `shot_tools.events.HookStart`
 +* `shot_tools.events.HookEnd`
 +
 +During usage we should see which one of these or other events are needed.
 +
 +`shot_tools.events.BuildStart`, `shot_tools.events.ProductionSettingsLoaded`
 +and `shot_tools.events.HookStart` can only be used in the `run_after`
 +parameter. `shot_tools.events.BuildFinished`, `shot_tools.events.HookFinished`
 +can only be used in the `run_before` parameter.
  
  
  ## API