add documentation for treevalue.utils.tree.build_tree

docs/source/api_doc/utils/index.rst

@@ -9,3 +9,4 @@ treevalue.utils
     final
     func
     singleton
+    tree

docs/source/api_doc/utils/tree.rst

+treevalue.utils.tree
+==========================
+
+build_tree
+~~~~~~~~~~~~~~~~~
+
+.. autofunction:: treevalue.utils.tree.build_tree

treevalue/utils/tree.py

@@ -7,6 +7,39 @@ _NODE_ID_TEMP = '_node_{id}'
 
 
 def build_tree(root, represent=None, iterate=None, recurse=None) -> LibTree:
+    """
+    Overview:
+        Build a treelib object by an object.
+
+    Arguments:
+        - root (:obj:`Any`): Root object.
+        - represent (:obj:`Optional[Callable]`): Represent function, default is primitive `repr`.
+        - iterate (:obj:`Optional[Callable]`): Iterate function, default is `lambda x: x.items()`.
+        - recurse (:obj:`Optional[Callable]`): Recurse check function, default is `lambda x: hasattr(x, 'items')`.
+
+    Returns:
+        - tree (:obj:`treelib.Tree`): Built tree.
+
+    Example:
+         >>> t = build_tree(
+         >>>     {'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}, 'z': [1, 2], 'v': {'1': '2'}},
+         >>>     represent=lambda x: '<node>' if isinstance(x, dict) else repr(x),
+         >>>     recurse=lambda x: isinstance(x, dict),
+         >>> )
+         >>> print(t)
+
+         The output should be
+
+         >>> <node>
+         >>> ├── 'a' --> 1
+         >>> ├── 'b' --> 2
+         >>> ├── 'v' --> <node>
+         >>> │   └── '1' --> '2'
+         >>> ├── 'x' --> <node>
+         >>> │   ├── 'c' --> 3
+         >>> │   └── 'd' --> 4
+         >>> └── 'z' --> [1, 2]
+    """
     represent = represent or repr
     iterate = iterate or (lambda x: x.items())
     recurse = recurse or (lambda x: hasattr(x, 'items'))