From f191c3317941ade634314acda277fb6b7bdd5bd6 Mon Sep 17 00:00:00 2001
From: Jakub Jezek <jakubjezek001@gmail.com>
Date: Tue, 10 Jan 2023 17:05:38 +0100
Subject: [PATCH] Global: adding more docstrings and README

---
 openpype/pipeline/README.md                  | 29 ++++++++++++++++
 openpype/pipeline/publish/publish_plugins.py | 35 +++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 openpype/pipeline/README.md

diff --git a/openpype/pipeline/README.md b/openpype/pipeline/README.md
new file mode 100644
index 0000000000..2c557f908d
--- /dev/null
+++ b/openpype/pipeline/README.md
@@ -0,0 +1,29 @@
+# Colorspace
+1. Each host handling pixle data is requiring setting schema.
+```json
+{
+    "key": "imageio",
+    "type": "dict",
+    "label": "Color Management (ImageIO)",
+    "is_group": true,
+    "children": [
+        {
+            "type": "schema",
+            "name": "schema_imageio_config"
+        },
+        {
+            "type": "schema",
+            "name": "schema_imageio_file_rules"
+        }
+
+    ]
+}
+```
+
+1. Use any mechanism to set OCIO config to host app resolved from `openpype\pipeline\colorspace.py:get_imageio_config`
+	-	either set OCIO environment during host launching via pre-launch hook
+	- or to set workfile ocio config path if host api is available
+
+2. Each pixle related exporter plugins has to use parent class `openpype\pipeline\publish\publish_plugins.py:ExtractorColormanaged` and use it similarly as it is already implemented here `openpype\hosts\nuke\plugins\publish\extract_render_local.py`
+- **get_colorspace_settings**: is solving all settings for the host context
+- **set_representation_colorspace**: is adding colorspaceData to representation. If the colorspace is known then it is added directly to the representation with resolved config path.
diff --git a/openpype/pipeline/publish/publish_plugins.py b/openpype/pipeline/publish/publish_plugins.py
index 16163495c4..07e2cdeec3 100644
--- a/openpype/pipeline/publish/publish_plugins.py
+++ b/openpype/pipeline/publish/publish_plugins.py
@@ -291,7 +291,9 @@ class Extractor(pyblish.api.InstancePlugin):
 class ExtractorColormanaged(Extractor):
     """Extractor base for color managed image data.
 
-    Class implements a "set_representation_colorspace" function, which is used
+    Each pixel data representation exctractors should be using this class
+    as parent. Class implements "get_colorspace_settings" and
+    "set_representation_colorspace" function, which is used
     for injecting colorspace data to representation data for farther
     integration into db document.
 
@@ -306,6 +308,14 @@ class ExtractorColormanaged(Extractor):
 
     @staticmethod
     def get_colorspace_settings(context):
+        """Retuns solved settings for the host context.
+
+        Args:
+            context (publish.Context): publishing context
+
+        Returns:
+            tuple | bool: config, file rules or None
+        """
         project_name = context.data["projectName"]
         host_name = context.data["hostName"]
         anatomy_data = context.data["anatomyData"]
@@ -327,7 +337,30 @@ class ExtractorColormanaged(Extractor):
         config_data, file_rules,
         colorspace=None
     ):
+        """Sets colorspace data to representation.
 
+        Args:
+            representation (dict): publishing representation
+            context (publish.Context): publishing context
+            config_data (dict): host resolved config data
+            file_rules (dict): host resolved file rules data
+            colorspace (str, optional): colorspace name. Defaults to None.
+
+        Example:
+            ```
+            {
+                # for other publish plugins and loaders
+                "colorspace": "linear",
+                "configData": {
+                    # for future references in case need
+                    "path": "/abs/path/to/config.ocio",
+                    # for other plugins within remote publish cases
+                    "template": "{project[root]}/path/to/config.ocio"
+                }
+            }
+            ```
+
+        """
         if not config_data:
             # warn in case no colorspace path was defined
             self.log.warning("No colorspace management was defined")