diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/conf.py | 187 | ||||
| -rw-r--r-- | docs/source/index.rst | 241 | ||||
| -rw-r--r-- | docs/source/modules.rst | 7 | ||||
| -rw-r--r-- | docs/source/treelib.rst | 45 |
4 files changed, 480 insertions, 0 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..11cb707 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,187 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + +from setup import __version__ + +# -- Project information ----------------------------------------------------- + +project = u'treelib' +copyright = u'2018, Xiaming Chen' +author = u'Xiaming Chen' + +# The short X.Y version +version = __version__ +# The full version, including alpha/beta/rc tags +release = __version__ + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'treelibdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'treelib.tex', u'treelib Documentation', + u'Xiaming Chen', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'treelib', u'treelib Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'treelib', u'treelib Documentation', + author, 'treelib', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None}
\ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2834bec --- /dev/null +++ b/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` diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..9e7d4d7 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +treelib +======= + +.. toctree:: + :maxdepth: 4 + + treelib diff --git a/docs/source/treelib.rst b/docs/source/treelib.rst new file mode 100644 index 0000000..c6034e9 --- /dev/null +++ b/docs/source/treelib.rst @@ -0,0 +1,45 @@ +treelib package +=============== + +Module contents +--------------- + +.. automodule:: treelib + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +treelib.node module +------------------- + +.. automodule:: treelib.node + :members: + :undoc-members: + :show-inheritance: + +treelib.tree module +------------------- + +.. automodule:: treelib.tree + :members: + :undoc-members: + :show-inheritance: + +treelib.plugins module +---------------------- + +.. automodule:: treelib.plugins + :members: + :undoc-members: + :show-inheritance: + +treelib.exceptions module +------------------------- + +.. automodule:: treelib.exceptions + :members: + :undoc-members: + :show-inheritance: |