Merge pull request #139 from jchanvfx/examples_#110

Examples #110

Author: jchanvfx

NodeGraphQt/__init__.py

@@ -30,45 +30,47 @@
 # OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 # EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 """
-NodeGraphQt is a node graph framework that can be implemented and re purposed
-into applications that supports PySide2.
+**NodeGraphQt** is a node graph framework that can be implemented and re purposed
+into applications that supports **PySide2**.
 
-url: https://github.com/jchanvfx/NodeGraphQt
-docs: http://chantasticvfx.com/nodeGraphQt/html/index.html
+project: https://github.com/jchanvfx/NodeGraphQt
 
-Basic Example:
+example code:
 
-import sys
-from NodeGraphQt import QtWidgets, NodeGraph, BaseNode
+.. code-block:: python
+    :linenos:
 
+    import sys
+    from NodeGraphQt import QtWidgets, NodeGraph, BaseNode
 
-class MyNode(BaseNode):
 
-    __identifier__ = 'com.chantasticvfx'
-    NODE_NAME = 'My Node'
+    class MyNode(BaseNode):
 
-    def __init__(self):
-        super(MyNode, self).__init__()
-        self.add_input('foo', color=(180, 80, 0))
-        self.add_output('bar')
+        __identifier__ = 'com.chantasticvfx'
+        NODE_NAME = 'My Node'
 
-if __name__ == '__main__':
-    app = QtWidgets.QApplication(sys.argv)
-    graph = NodeGraph()
+        def __init__(self):
+            super(MyNode, self).__init__()
+            self.add_input('foo', color=(180, 80, 0))
+            self.add_output('bar')
 
-    graph.register_node(BaseNode)
-    graph.register_node(BackdropNode)
+    if __name__ == '__main__':
+        app = QtWidgets.QApplication(sys.argv)
+        graph = NodeGraph()
 
-    backdrop = graph.create_node('nodeGraphQt.nodes.Backdrop', name='Backdrop')
-    node_a = graph.create_node('com.chantasticvfx.MyNode', name='Node A')
-    node_b = graph.create_node('com.chantasticvfx.MyNode', name='Node B', color='#5b162f')
+        graph.register_node(BaseNode)
+        graph.register_node(BackdropNode)
 
-    node_a.set_input(0, node_b.output(0))
+        backdrop = graph.create_node('nodeGraphQt.nodes.Backdrop', name='Backdrop')
+        node_a = graph.create_node('com.chantasticvfx.MyNode', name='Node A')
+        node_b = graph.create_node('com.chantasticvfx.MyNode', name='Node B', color='#5b162f')
 
-    viewer = graph.viewer()
-    viewer.show()
+        node_a.set_input(0, node_b.output(0))
 
-    app.exec_()
+        viewer = graph.viewer()
+        viewer.show()
+
+        app.exec_()
 """
 
 try:

NodeGraphQt/base/graph.py

@@ -26,28 +26,68 @@ class NodeGraph(QtCore.QObject):
     """
     The ``NodeGraph`` class is the main controller for managing all nodes.
 
-    Inherited from: ``PySide2.QtCore.QObject``
+    Inherited from: :class:`PySide2.QtCore.QObject`
 
     .. image:: _images/graph.png
         :width: 60%
     """
 
-    #:QtCore.Signal: emits the node object when a node is created in the node graph.
     node_created = QtCore.Signal(NodeObject)
-    #:QtCore.Signal: emits a ``list[str]`` of node ids from the deleted nodes.
+    """
+    Signal triggered when a node is created in the node graph.
+    
+    :parameters: :class:`NodeGraphQt.NodeObject`
+    :emits: created node
+    """
     nodes_deleted = QtCore.Signal(list)
-    #:QtCore.Signal: emits the node object when selected in the node graph.
+    """
+    Signal triggered when nodes have been deleted from the node graph.
+
+    :parameters: list[str]
+    :emits: list of deleted node ids.
+    """
     node_selected = QtCore.Signal(NodeObject)
-    #:QtCore.Signal: triggered when a node is double clicked and emits the node.
+    """
+    Signal triggered when a node is clicked with the LMB.
+    
+    :parameters: :class:`NodeGraphQt.NodeObject`
+    :emits: selected node
+    """
     node_double_clicked = QtCore.Signal(NodeObject)
-    #:QtCore.Signal: for when a node has been connected emits (``input port``, ``output port``).
+    """
+    Signal triggered when a node is double clicked and emits the node.
+
+    :parameters: :class:`NodeGraphQt.NodeObject`
+    :emits: selected node
+    """
     port_connected = QtCore.Signal(Port, Port)
-    #:QtCore.Signal: for when a node has been disconnected emits (``input port``, ``output port``).
+    """
+    Signal triggered when a node port has been connected.
+
+    :parameters: :class:`NodeGraphQt.Port`, :class:`NodeGraphQt.Port` 
+    :emits: input port, output port
+    """
     port_disconnected = QtCore.Signal(Port, Port)
-    #:QtCore.Signal: for when a node property has changed emits (``node``, ``property name``, ``property value``).
+    """
+    Signal triggered when a node port has been disconnected.
+
+    :parameters: :class:`NodeGraphQt.Port`, :class:`NodeGraphQt.Port` 
+    :emits: input port, output port
+    """
     property_changed = QtCore.Signal(NodeObject, str, object)
-    #:QtCore.Signal: for when drop data has been added to the graph.
+    """
+    Signal is triggered when a property has changed on a node.  
+
+    :parameters: :class:`NodeGraphQt.BaseNode`, str, object
+    :emits: triggered node, property name, property value
+    """
     data_dropped = QtCore.Signal(QtCore.QMimeData, QtCore.QPoint)
+    """
+    Signal is triggered when data has been dropped to the graph.
+    
+    :parameters: :class:`PySide2.QtCore.QMimeData`, :class:`PySide2.QtCore.QPoint`
+    :emits: mime data, node graph position
+    """
 
     def __init__(self, parent=None):
         super(NodeGraph, self).__init__(parent)
@@ -237,7 +277,7 @@ def widget(self):
         The node graph widget for adding into a layout.
 
         Returns:
-            QtWidgets.QWidget: node graph widget.
+            PySide2.QtWidgets.QWidget: node graph widget.
         """
         if self._widget is None:
             self._widget = QtWidgets.QWidget()
@@ -249,16 +289,16 @@ def widget(self):
     def show(self):
         """
         Show node graph widget this is just a convenience
-        function to :meth:`NodeGraph.widget().show()`.
+        function to :meth:`NodeGraph.widget.show()`.
         """
-        self._widget.show()
+        self.widget.show()
 
     def close(self):
         """
         Close node graph NodeViewer widget this is just a convenience
-        function to :meth:`NodeGraph.widget().close()`.
+        function to :meth:`NodeGraph.widget.close()`.
         """
-        self._widget.close()
+        self.widget.close()
 
     def viewer(self):
         """
@@ -270,7 +310,7 @@ def viewer(self):
 
         See Also:
             :attr:`NodeGraph.widget` for adding the node graph into a 
-            QtWidgets.QLayout.
+            :class:`PySide2.QtWidgets.QLayout`.
 
         Returns:
             NodeGraphQt.widgets.viewer.NodeViewer: viewer interface.
@@ -429,7 +469,7 @@ def get_context_menu(self, menu):
             menu (str): menu name.
 
         Returns:
-            NodeGraphMenu or NodesMenu: context menu object.
+            NodeGraphQt.NodeGraphMenu or NodeGraphQt.NodesMenu: context menu object.
         """
         menus = self._viewer.context_menus()
         if menus.get(menu):

NodeGraphQt/base/menu.py

@@ -8,7 +8,7 @@
 
 class NodeGraphMenu(object):
     """
-    The ``NodeGraphMenu`` is the context menu triggered from the node graph.
+    The ``NodeGraphMenu`` is the main context menu triggered from the node graph.
 
     example for accessing the node graph context menu.
 
@@ -22,8 +22,6 @@ class NodeGraphMenu(object):
         # get the context menu for the node graph.
         context_menu = node_graph.get_context_menu('graph')
 
-        print(context_menu)
-        # >> <NodeGraphMenu("NodeGraph") object at 0x10910fdd8>
     """
 
     def __init__(self, graph, qmenu):
@@ -124,7 +122,7 @@ def add_command(self, name, func=None, shortcut=None):
             shortcut (str): shotcut key.
 
         Returns:
-            NodeGraphQt.MenuCommand: the appended command.
+            NodeGraphQt.NodeGraphCommand: the appended command.
         """
         action = GraphAction(name, self._graph.viewer())
         action.graph = self._graph
@@ -146,45 +144,21 @@ def add_separator(self):
 
 class NodesMenu(NodeGraphMenu):
     """
-    The ``NodesMenu`` is the context menu triggered from the nodes.
+    The ``NodesMenu`` is the context menu triggered from a node.
 
     **Inherited from:** :class:`NodeGraphQt.NodeGraphMenu`
 
-    example for adding a command to the nodes context menu.
+    example for accessing the nodes context menu.
 
     .. code-block:: python
         :linenos:
 
-        from NodeGraphQt import BaseNode, NodeGraph
-
-        # example node.
-        class MyNode(BaseNode):
-
-            __identifier__ = 'com.chantasticvfx'
-            NODE_NAME = 'my node'
-
-            def __init__(self):
-                super(MyNode, self).__init__()
-                self.add_input('in')
-                self.add_output('out')
+        from NodeGraphQt import NodeGraph
 
-        # create node graph.
         node_graph = NodeGraph()
 
-        # register example node.
-        node_graph.register_node(MyNode)
-
-        # get the context menu for the nodes.
+        # get the nodes context menu.
         nodes_menu = node_graph.get_context_menu('nodes')
-
-        # create a command
-        def test_func(graph, node):
-            print('Clicked on node: {}'.format(node.name()))
-
-        nodes_menu.add_command('test',
-                               func=test_func,
-                               node_type='com.chantasticvfx.MyNode')
-
     """
 
     def add_command(self, name, func=None, node_type=None):
@@ -197,7 +171,7 @@ def add_command(self, name, func=None, node_type=None):
             node_type (str): specified node type for the command.
 
         Returns:
-            NodeGraphQt.MenuCommand: the appended command.
+            NodeGraphQt.NodeGraphCommand: the appended command.
         """
         if not node_type:
             raise NodeMenuError('Node type not specified!')
@@ -239,7 +213,7 @@ def qaction(self):
         The underlying qaction.
 
         Returns:
-            BaseAction: qaction object.
+            GraphAction: qaction object.
         """
         return self._qaction
 

NodeGraphQt/base/node.py

@@ -36,10 +36,10 @@ class NodeObject(object):
         qgraphics_item (AbstractNodeItem): graphic item used for drawing.
     """
 
-    #:str: unique node identifier domain.
+    # Unique node identifier domain. `eg.` ``"com.chantacticvfx"``
     __identifier__ = 'nodeGraphQt.nodes'
 
-    #:str: base node name.
+    # Base node name.
     NODE_NAME = None
 
     def __init__(self, qgraphics_item=None):
@@ -61,7 +61,7 @@ def __repr__(self):
     def type_(cls):
         """
         Node type identifier followed by the class name.
-        eg. nodeGraphQt.nodes.MyNode
+        `eg.` ``"com.chantacticvfx.NodeObject"``
 
         Returns:
             str: node type.

NodeGraphQt/base/utils.py

@@ -6,7 +6,9 @@
 
 def setup_context_menu(graph):
     """
-    Sets up the node graphs context menu with some basic menus and commands.
+    populate the specified graph's context menu with essential menus commands.
+
+    example code:
 
     .. code-block:: python
         :linenos:
@@ -16,6 +18,11 @@ def setup_context_menu(graph):
         graph = NodeGraph()
         setup_context_menu(graph)
 
+    result:
+
+    .. image:: _images/menu_hotkeys.png
+        :width: 300px
+
     Args:
         graph (NodeGraphQt.NodeGraph): node graph.
     """

docs/_images/selection.png

@@ -4,4 +4,3 @@ Constants
 .. automodule:: NodeGraphQt.constants
     :members:
     :member-order: bysource
-    :noindex: