Adding upstream version 1.6.4.

Signed-off-by: Daniel Baumann <daniel@debian.org>

docs/source/index.rst

@@ -0,0 +1,241 @@
+.. treelib documentation master file, created by
+   sphinx-quickstart on Thu Dec 20 16:30:18 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to treelib's documentation!
+***********************************
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Introduction
+============
+
+`Tree <http://en.wikipedia.org/wiki/Tree_%28data_structure%29>`_ is an
+important data structure in computer science. Examples are shown in ML algorithm designs such as random forest tree and software engineering such as file system index. `treelib <https://github.com/caesar0301/pyTree>`_ is created to provide an efficient implementation of tree data structure in Python.
+
+The main features of `treelib` includes:
+   * Efficient operation of node searching, O(1).
+   * Support common tree operations like **traversing**, **insertion**, **deletion**, **node moving**, **shallow/deep copying**, **subtree cutting** etc.
+   * Support user-defined data payload to accelerate your model construction.
+   * Pretty tree showing and text/json dump for pretty show and offline analysis.
+   * Compatible with Python 2 and 3.
+
+Installation
+============
+
+The rapidest way to install treelib is using the package management tools like
+``easy_install`` or ``pip`` with command
+
+	.. code-block:: sh
+
+		$ sudo easy_install -U treelib
+
+or the setup script
+
+	.. code-block:: sh
+
+		$ sudo python setup.py install
+
+**Note**: With the package management tools, the hosted version may be falling
+behind current development branch on `Github
+<https://github.com/caesar0301/pyTree>`_. If you encounter some problems, try
+the freshest version on Github or open `issues
+<https://github.com/caesar0301/pyTree/issues>`_ to let me know your problem.
+
+Examples
+========
+
+Basic Usage
+-------------
+
+.. code-block:: sh
+
+    >>> from treelib import Node, Tree
+    >>> tree = Tree()
+    >>> tree.create_node("Harry", "harry")  # root node
+    >>> tree.create_node("Jane", "jane", parent="harry")
+    >>> tree.create_node("Bill", "bill", parent="harry")
+    >>> tree.create_node("Diane", "diane", parent="jane")
+    >>> tree.create_node("Mary", "mary", parent="diane")
+    >>> tree.create_node("Mark", "mark", parent="jane")
+    >>> tree.show()
+    Harry
+    ├── Bill
+    └── Jane
+        ├── Diane
+        │   └── Mary
+        └── Mark
+
+
+API Examples
+--------------
+
+**Example 1**: Expand a tree with specific mode (Tree.DEPTH [default],
+Tree.WIDTH, Tree.ZIGZAG).
+
+.. code-block:: sh
+
+    >>> print(','.join([tree[node].tag for node in \
+                tree.expand_tree(mode=Tree.DEPTH)]))
+    Harry,Bill,Jane,Diane,Mary,Mark
+
+**Example 2**: Expand tree with custom filter.
+
+.. code-block:: sh
+
+    >>> print(','.join([tree[node].tag for node in \
+                tree.expand_tree(filter = lambda x: \
+                x.identifier != 'diane')]))
+    Harry,Bill,Jane,Mark
+
+**Example 3**: Get a subtree with the root of 'diane'.
+
+.. code-block:: sh
+
+    >>> sub_t = tree.subtree('diane')
+    >>> sub_t.show()
+    Diane
+    └── Mary
+
+**Example 4**: Paste a new tree to the original one.
+
+.. code-block:: sh
+
+    >>> new_tree = Tree()
+    >>> new_tree.create_node("n1", 1)  # root node
+    >>> new_tree.create_node("n2", 2, parent=1)
+    >>> new_tree.create_node("n3", 3, parent=1)
+    >>> tree.paste('bill', new_tree)
+    >>> tree.show()
+    Harry
+    ├── Bill
+    │   └── n1
+    │       ├── n2
+    │       └── n3
+    └── Jane
+        ├── Diane
+        │   └── Mary
+        └── Mark
+
+**Example 5**: Remove the existing node from the tree
+
+.. code-block:: sh
+
+    >>> tree.remove_node(1)
+    >>> tree.show()
+    Harry
+    ├── Bill
+    └── Jane
+        ├── Diane
+        │   └── Mary
+        └── Mark
+
+**Example 6**: Move a node to another parent.
+
+.. code-block:: sh
+
+    >>> tree.move_node('mary', 'harry')
+    >>> tree.show()
+    Harry
+    ├── Bill
+    ├── Jane
+    │   ├── Diane
+    │   └── Mark
+    └── Mary
+
+**Example 7**: Get the height of the tree.
+
+.. code-block:: sh
+
+    >>> tree.depth()
+    2
+
+**Example 8**: Get the level of a node.
+
+.. code-block:: sh
+
+    >>> node = tree.get_node("bill")
+    >>> tree.depth(node)
+    1
+
+**Example 9**: Print or dump tree structure. For example, the same tree in
+ basic example can be printed with 'ascii-em':
+
+.. code-block:: sh
+
+    >>> tree.show(line_type="ascii-em")
+    Harry
+    ╠══ Bill
+    ╠══ Jane
+    ║   ╠══ Diane
+    ║   ╚══ Mark
+    ╚══ Mary
+
+In the JSON form, to_json() takes optional parameter with_data to trigger if
+the data field is appended into JSON string. For example,
+
+.. code-block:: sh
+
+    >>> print(tree.to_json(with_data=True))
+    {"Harry": {"data": null, "children": [{"Bill": {"data": null}}, {"Jane": {"data": null, "children": [{"Diane": {"data": null}}, {"Mark": {"data": null}}]}}, {"Mary": {"data": null}}]}}
+
+**Example 10**: Save tree into file
+  The function save2file require a filename.
+  The file is opened to write using mode 'ab'.
+
+.. code-block:: sh
+
+    >>> tree.save2file('tree.txt')
+
+
+Advanced Usage
+----------------
+
+Sometimes, you need trees to store your own data. The newest version of
+:mod:`treelib` supports ``.data`` variable to store whatever you want. For
+example, to define a flower tree with your own data:
+
+.. code-block:: sh
+
+    >>> class Flower(object): \
+            def __init__(self, color): \
+                self.color = color
+
+You can create a flower tree now:
+
+.. code-block:: sh
+
+    >>> ftree = Tree()
+    >>> ftree.create_node("Root", "root", data=Flower("black"))
+    >>> ftree.create_node("F1", "f1", parent='root', data=Flower("white"))
+    >>> ftree.create_node("F2", "f2", parent='root', data=Flower("red"))
+
+Printing the colors of the tree:
+
+.. code-block:: sh
+
+    >>> ftree.show(data_property="color")
+        black
+        ├── white
+        └── red
+
+**Notes:** Before version 1.2.5, you may need to inherit and modify the behaviors of tree. Both are supported since then. For flower example,
+
+.. code-block:: sh
+
+    >>> class FlowerNode(treelib.Node): \
+            def __init__(self, color): \
+                self.color = color
+    >>> # create a new node
+    >>> fnode = FlowerNode("white")
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`