Improve the document of learning.Graph (#1277)

docs/reference/session.rst

@@ -22,4 +22,4 @@ Session Functions
    graphscope.get_option
    graphscope.g
    graphscope.gremlin
-   graphscope.learning
+   graphscope.graphlearn

python/graphscope/client/session.py

@@ -1168,13 +1168,49 @@ def graphlearn(self, graph, nodes=None, edges=None, gen_labels=None):
         """Start a graph learning engine.
 
         Args:
-            nodes (list): The node types that will be used for gnn training.
-            edges (list): The edge types that will be used for gnn training.
-            gen_labels (list): Extra node and edge labels on original graph for gnn training.
-
-        Returns:
-            :class:`graphscope.learning.GraphDAGNode`:
-                An instance of learning graph that could be feed to the learning engine, evaluated in eager node.
+            graph (:class:`graphscope.framework.graph.GraphDAGNode`):
+                The graph to create learning instance.
+            nodes (list, optional): list of node types that will be used for GNN
+                training, the element of list can be `"node_label"` or
+                `(node_label, features)`. If the element of the list is a tuple and
+                contains selected feature list, it would use the selected
+                feature list for training. Default is None which use all type of
+                nodes and for the GNN training.
+            edges (list, optional): list of edge types that will be used for GNN
+                training. We use `(src_label, edge_label, dst_label)`
+                to specify one edge type. Default is None which use all type of
+                edges for GNN training.
+            gen_labels (list, optional): Alias node and edge labels and extract
+                train/validation/test dataset from original graph for supervised
+                GNN training. The detail is explained in the examples below.
+
+        Examples
+        --------
+        >>> # Assume the input graph contains one label node `paper` and one edge label `link`.
+        >>> features = ["weight", "name"] # use properties "weight" and "name" as features
+        >>> lg = sess.graphlearn(
+                graph,
+                nodes=[("paper", features)])  # use "paper" node and features for training
+                edges=[("paper", "links", "paper")]  # use the `paper->links->papers` edge type for training
+                gen_labels=[
+                    # split "paper" nodes into 100 pieces, and uses random 75 pieces (75%) as training dataset
+                    ("train", "paper", 100, (0, 75)),
+                    # split "paper" nodes into 100 pieces, and uses random 10 pieces (10%) as validation dataset
+                    ("val", "paper", 100, (75, 85)),
+                    # split "paper" nodes into 100 pieces, and uses random 15 pieces (15%) as test dataset
+                    ("test", "paper", 100, (85, 100)),
+                ]
+            )
+        Note that the training, validation and test datasets are not overlapping. And for unsupervised learning:
+        >>> lg = sess.graphlearn(
+                graph,
+                nodes=[("paper", features)])  # use "paper" node and features for training
+                edges=[("paper", "links", "paper")]  # use the `paper->links->papers` edge type for training
+                gen_labels=[
+                    # split "paper" nodes into 100 pieces, and uses all pieces as training dataset
+                    ("train", "paper", 100, (0, 100)),
+                ]
+            )
         """
         if self._session_id != graph.session_id:
             raise RuntimeError(
@@ -1458,7 +1494,7 @@ def gremlin(graph, engine_params=None):
 def graphlearn(graph, nodes=None, edges=None, gen_labels=None):
     """Create a graph learning engine.
 
-    See params detail in :meth:`graphscope.Session.learning`
+    See params detail in :meth:`graphscope.Session.graphlearn`
 
     Returns:
         :class:`graphscope.learning.GraphDAGNode`:

python/graphscope/learning/graph.py

@@ -52,13 +52,7 @@ class GraphDAGNode(DAGNode):
 
     def __init__(self, session, graph, nodes=None, edges=None, gen_labels=None):
         """
-        Args:
-            session (:class:`Session`): instance of GraphScope session.
-            graph (:class:`graphscope.framework.graph.GraphDAGNode`):
-                Source property graph.
-            nodes (list): The node types that will be used for gnn training.
-            edges (list): The edge types that will be used for gnn training.
-            gen_labels (list): Extra node and edge labels on original graph for gnn training.
+        See params detail in :meth:`graphscope.Session.graphlearn`
         """
         self._session = session
         self._graph = graph