updated docs and doc strings.

jchanvfx · jchanvfx · commit e8058b439ea4 · 2020-04-19T19:53:13.000+12:00
diff --git a/NodeGraphQt/base/node.py b/NodeGraphQt/base/node.py
@@ -936,22 +936,25 @@ def set_ports(self, port_data):
         Set node input and output ports.
 
         Args:
-            port_data(dict):
-                {
-                'input_ports':
-                    [{'name':...,
-                      'multi_connection':...,
-                      'display_name':...,
-                      'data_type':...
-                    }, ...],
-                'output_ports':
-                    [{'name':...,
-                      'multi_connection':...,
-                      'display_name':...,
-                      'data_type':...
-                    }, ...]
-                }
-        """
+            port_data(dict): port data.
+        """
+
+        # port data eg.
+        # {
+        #     'input_ports':
+        #         [{'name': ...,
+        #           'multi_connection': ...,
+        #           'display_name': ...,
+        #           'data_type': ...
+        #           }, ...],
+        #     'output_ports':
+        #         [{'name': ...,
+        #           'multi_connection': ...,
+        #           'display_name': ...,
+        #           'data_type': ...
+        #           }, ...]
+        # }
+
         for port in self._inputs:
             self._view.delete_input(port.view)
             port.model.node = None
@@ -1231,6 +1234,12 @@ class SubGraph(object):
     """
     The ``NodeGraphQt.SubGraph`` class is the base class that all
     Sub Graph Node inherit from.
+
+    *Implemented on NodeGraphQt: * ``v0.1.0``
+
+    .. image:: _images/example_subgraph.gif
+        :width: 80%
+
     """
 
     def __init__(self):
@@ -1245,8 +1254,9 @@ def children(self):
     def create_from_nodes(self, nodes):
         """
         Create sub graph from the nodes.
+
         Args:
-            nodes(list): nodes to create the sub graph.
+            nodes (list[NodeGraphQt.NodeObject]): nodes to create the sub graph.
         """
         if self in nodes:
             nodes.remove(self)
@@ -1257,7 +1267,7 @@ def add_child(self, node):
         Add a node to the sub graph.
 
         Args:
-            node(NodeGraphQt.BaseNode).
+            node (NodeGraphQt.BaseNode): node object.
         """
         self._children.add(node)
 
@@ -1266,7 +1276,7 @@ def remove_child(self, node):
         Remove a node from the sub graph.
 
         Args:
-            node(NodeGraphQt.BaseNode).
+            node (NodeGraphQt.BaseNode): node object.
         """
         if node in self._children:
             self._children.remove(node)
diff --git a/NodeGraphQt/base/utils.py b/NodeGraphQt/base/utils.py
@@ -498,8 +498,12 @@ def topological_sort_by_down(start_nodes=None, all_nodes=None):
     'start_nodes' and 'all_nodes' only one needs to be given.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode])(Optional):
+            the start update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode])(Optional):
+            if 'start_nodes' is None the function can calculate start nodes
+            from 'all_nodes'.
+
     Returns:
         list[NodeGraphQt.BaseNode]: sorted nodes.
     """
@@ -528,8 +532,11 @@ def topological_sort_by_up(start_nodes=None, all_nodes=None):
     'start_nodes' and 'all_nodes' only one needs to be given.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode])(Optional):
+            the end update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode])(Optional):
+            if 'start_nodes' is None the function can calculate start nodes
+            from 'all_nodes'.
     Returns:
         list[NodeGraphQt.BaseNode]: sorted nodes.
     """
@@ -632,11 +639,12 @@ def _compute_rank_down(start_nodes):
     Compute the rank of the down stream nodes.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start nodes of the graph.
+        start_nodes (list[NodeGraphQt.BaseNode])(Optional):
+            the start nodes of the graph.
+
     Returns:
         dict{NodeGraphQt.BaseNode: node_rank, ...}
     """
-
     nodes_rank = {}
     for node in start_nodes:
         nodes_rank[node] = 0
@@ -659,7 +667,9 @@ def _compute_rank_up(start_nodes):
     Compute the rank of the up stream nodes.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end nodes of the graph.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the end nodes of the graph.
+
     Returns:
         dict{NodeGraphQt.BaseNode: node_rank, ...}
     """
@@ -676,8 +686,11 @@ def auto_layout_up(start_nodes=None, all_nodes=None):
     Auto layout the nodes by up stream direction.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the end nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
     """
     if not start_nodes and not all_nodes:
         return
@@ -737,8 +750,11 @@ def auto_layout_down(start_nodes=None, all_nodes=None):
     Auto layout the nodes by down stream direction.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the start update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
     """
     if not start_nodes and not all_nodes:
         return
diff --git a/docs/_images/example_subgraph.gif b/docs/_images/example_subgraph.gif
diff --git a/docs/examples/ex_node.rst b/docs/examples/ex_node.rst
@@ -41,7 +41,7 @@ Creating Nodes
 Embedding Widgets
 *****************
 
-The :meth:`NodeGraphQt.BaseNode` class allows you to embed widgets inside a node here's a
+The :class:`NodeGraphQt.BaseNode` class allows you to embed widgets inside a node here's a
 example to simply embed a ``QComboBox`` widget when reimplementing the ``BaseNode``.
 
 .. code-block:: python
diff --git a/docs/examples/ex_port.rst b/docs/examples/ex_port.rst
@@ -0,0 +1,130 @@
+Port Examples
+#############
+
+Creating Custom Shapes
+**********************
+
+*(Implemented on NodeGraphQt* ``v0.1.1`` *or above)*
+
+To have custom port shapes the :meth:`NodeGraphQt.BaseNode.add_input` and
+:meth:`NodeGraphQt.BaseNode.add_output` functions now have a ``painter_func``
+argument where you specify you custom port painter function.
+
+Example Triangle Port
+*********************
+
+Here's an example function for drawing a triangle shaped port.
+
+.. code-block:: python
+    :linenos:
+
+    def draw_triangle_port(painter, rect, info):
+        """
+        Custom paint function for drawing a Triangle shaped port.
+
+        Args:
+            painter (QtGui.QPainter): painter object.
+            rect (QtCore.QRectF): port rect used to describe parameters
+                                  needed to draw.
+            info (dict): information describing the ports current state.
+                {
+                    'port_type': 'in',
+                    'color': (0, 0, 0),
+                    'border_color': (255, 255, 255),
+                    'multi_connection': False,
+                    'connected': False,
+                    'hovered': False,
+                }
+        """
+        painter.save()
+
+        size = int(rect.height() / 2)
+        triangle = QtGui.QPolygonF()
+        triangle.append(QtCore.QPointF(-size, size))
+        triangle.append(QtCore.QPointF(0.0, -size))
+        triangle.append(QtCore.QPointF(size, size))
+
+        transform = QtGui.QTransform()
+        transform.translate(rect.center().x(), rect.center().y())
+        port_poly = transform.map(triangle)
+
+        # mouse over port color.
+        if info['hovered']:
+            color = QtGui.QColor(14, 45, 59)
+            border_color = QtGui.QColor(136, 255, 35)
+        # port connected color.
+        elif info['connected']:
+            color = QtGui.QColor(195, 60, 60)
+            border_color = QtGui.QColor(200, 130, 70)
+        # default port color
+        else:
+            color = QtGui.QColor(*info['color'])
+            border_color = QtGui.QColor(*info['border_color'])
+
+        pen = QtGui.QPen(border_color, 1.8)
+        painter.setPen(pen)
+        painter.setBrush(color)
+        painter.drawPolygon(port_poly)
+
+        painter.restore()
+
+The ``draw_triangle_port`` painter function can then be passed to the ``painter_func`` arg.
+
+.. code-block:: python
+    :linenos:
+
+    from NodeGraphQt import BaseNode
+
+    class MyListNode(BaseNode):
+
+        def __init__(self):
+            super(MyListNode, self).__init__()
+            self.add_input('triangle', painter_func=draw_triangle_port)
+
+Example Square Port
+*******************
+
+Here's simpler example function for drawing a Square shaped port.
+
+.. code-block:: python
+    :linenos:
+
+    def draw_square_port(painter, rect, info):
+        """
+        Custom paint function for drawing a Square shaped port.
+
+        Args:
+            painter (QtGui.QPainter): painter object.
+            rect (QtCore.QRectF): port rect used to describe parameters
+                                  needed to draw.
+            info (dict): information describing the ports current state.
+                {
+                    'port_type': 'in',
+                    'color': (0, 0, 0),
+                    'border_color': (255, 255, 255),
+                    'multi_connection': False,
+                    'connected': False,
+                    'hovered': False,
+                }
+        """
+        painter.save()
+
+        # mouse over port color.
+        if info['hovered']:
+            color = QtGui.QColor(14, 45, 59)
+            border_color = QtGui.QColor(136, 255, 35, 255)
+        # port connected color.
+        elif info['connected']:
+            color = QtGui.QColor(195, 60, 60)
+            border_color = QtGui.QColor(200, 130, 70)
+        # default port color
+        else:
+            color = QtGui.QColor(*info['color'])
+            border_color = QtGui.QColor(*info['border_color'])
+
+        pen = QtGui.QPen(border_color, 1.8)
+        painter.setPen(pen)
+        painter.setBrush(color)
+        painter.drawRect(rect)
+
+        painter.restore()
diff --git a/docs/graph.rst b/docs/graph.rst
@@ -1,5 +1,8 @@
+Graphs
+######
+
 NodeGraph
-#########
+*********
 
 `See` :ref:`Basic Example` `from the NodeGraph overview.`
 
@@ -11,3 +14,10 @@ NodeGraph
 
     .. autoattribute:: NodeGraphQt.NodeGraph.widget
     .. autoattribute:: NodeGraphQt.NodeGraph.model
+
+
+SubGraph
+********
+
+.. autoclass:: NodeGraphQt.SubGraph
+    :members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -29,4 +29,5 @@ GitHub Project: https://github.com/jchanvfx/NodeGraphQt
 
     examples/ex_overview
     examples/ex_node
+    examples/ex_port
     examples/ex_menu
diff --git a/docs/nodes/SubGraphNode.rst b/docs/nodes/SubGraphNode.rst
diff --git a/example.py b/example.py
