Merge pull request #2896 from pypeclub/enhancement/OP-2930_New-publis…

…her-Develop-docs

Documentation: New publisher develop docs

openpype/hosts/testhost/plugins/create/auto_creator.py

@@ -30,7 +30,7 @@ def collect_instances(self):
     def update_instances(self, update_list):
         pipeline.update_instances(update_list)
 
-    def create(self, options=None):
+    def create(self):
         existing_instance = None
         for instance in self.create_context.instances:
             if instance.family == self.family:

openpype/pipeline/create/context.py

@@ -18,6 +18,8 @@
     get_project_settings
 )
 
+UpdateData = collections.namedtuple("UpdateData", ["instance", "changes"])
+
 
 class ImmutableKeyError(TypeError):
     """Accessed key is immutable so does not allow changes or removements."""
@@ -1082,7 +1084,7 @@ def _save_instance_changes(self):
             for instance in cretor_instances:
                 instance_changes = instance.changes()
                 if instance_changes:
-                    update_list.append((instance, instance_changes))
+                    update_list.append(UpdateData(instance, instance_changes))
 
             creator = self.creators[identifier]
             if update_list:

openpype/pipeline/create/creator_plugins.py

@@ -58,6 +58,11 @@ class BaseCreator:
     # - may not be used if `get_icon` is reimplemented
     icon = None
 
+    # Instance attribute definitions that can be changed per instance
+    # - returns list of attribute definitions from
+    #       `openpype.pipeline.attribute_definitions`
+    instance_attr_defs = []
+
     def __init__(
         self, create_context, system_settings, project_settings, headless=False
     ):
@@ -68,10 +73,13 @@ def __init__(
         # - we may use UI inside processing this attribute should be checked
         self.headless = headless
 
-    @abstractproperty
+    @property
     def identifier(self):
-        """Identifier of creator (must be unique)."""
-        pass
+        """Identifier of creator (must be unique).
+
+        Default implementation returns plugin's family.
+        """
+        return self.family
 
     @abstractproperty
     def family(self):
@@ -102,11 +110,39 @@ def create(self):
         pass
 
     @abstractmethod
-    def collect_instances(self, attr_plugins=None):
+    def collect_instances(self):
+        """Collect existing instances related to this creator plugin.
+
+        The implementation differs on host abilities. The creator has to
+        collect metadata about instance and create 'CreatedInstance' object
+        which should be added to 'CreateContext'.
+
+        Example:
+        ```python
+        def collect_instances(self):
+            # Getting existing instances is different per host implementation
+            for instance_data in pipeline.list_instances():
+                # Process only instances that were created by this creator
+                creator_id = instance_data.get("creator_identifier")
+                if creator_id == self.identifier:
+                    # Create instance object from existing data
+                    instance = CreatedInstance.from_existing(
+                        instance_data, self
+                    )
+                    # Add instance to create context
+                    self._add_instance_to_context(instance)
+        ```
+        """
         pass
 
     @abstractmethod
     def update_instances(self, update_list):
+        """Store changes of existing instances so they can be recollected.
+
+        Args:
+            update_list(list<UpdateData>): Gets list of tuples. Each item
+                contain changed instance and it's changes.
+        """
         pass
 
     @abstractmethod
@@ -190,7 +226,7 @@ def get_instance_attr_defs(self):
             list<AbtractAttrDef>: Attribute definitions that can be tweaked for
                 created instance.
         """
-        return []
+        return self.instance_attr_defs
 
 
 class Creator(BaseCreator):
@@ -203,6 +239,9 @@ class Creator(BaseCreator):
     # - default_variants may not be used if `get_default_variants` is overriden
     default_variants = []
 
+    # Default variant used in 'get_default_variant'
+    default_variant = None
+
     # Short description of family
     # - may not be used if `get_description` is overriden
     description = None
@@ -216,6 +255,10 @@ class Creator(BaseCreator):
     #      e.g. for buld creators
     create_allow_context_change = True
 
+    # Precreate attribute definitions showed before creation
+    # - similar to instance attribute definitions
+    pre_create_attr_defs = []
+
     @abstractmethod
     def create(self, subset_name, instance_data, pre_create_data):
         """Create new instance and store it.
@@ -275,7 +318,7 @@ def get_default_variant(self):
         `get_default_variants` should be used.
         """
 
-        return None
+        return self.default_variant
 
     def get_pre_create_attr_defs(self):
         """Plugin attribute definitions needed for creation.
@@ -288,7 +331,7 @@ def get_pre_create_attr_defs(self):
             list<AbtractAttrDef>: Attribute definitions that can be tweaked for
                 created instance.
         """
-        return []
+        return self.pre_create_attr_defs
 
 
 class AutoCreator(BaseCreator):