From 3a36149e5845e9401d5a442a80cd081c965487c7 Mon Sep 17 00:00:00 2001 From: Leonard Binet Date: Sat, 20 Jun 2020 23:06:29 +0200 Subject: [PATCH] lighttree documentation --- docs/Makefile | 32 +++ docs/__init__.py | 0 docs/source/CONTRIBUTING.md | 46 +++++ docs/source/__init__.py | 0 docs/source/conf.py | 188 ++++++++++++++++++ docs/source/index.rst | 50 +++++ .../source/reference/lighttree.exceptions.rst | 7 + .../reference/lighttree.interactive.rst | 7 + docs/source/reference/lighttree.node.rst | 7 + docs/source/reference/lighttree.rst | 22 ++ docs/source/reference/lighttree.tree.rst | 7 + docs/source/reference/lighttree.utils.rst | 7 + docs/source/requirements.txt | 2 + docs/source/user-guide.rst | 13 ++ lighttree/tree.py | 27 ++- 15 files changed, 409 insertions(+), 6 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/__init__.py create mode 100644 docs/source/CONTRIBUTING.md create mode 100644 docs/source/__init__.py create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/reference/lighttree.exceptions.rst create mode 100644 docs/source/reference/lighttree.interactive.rst create mode 100644 docs/source/reference/lighttree.node.rst create mode 100644 docs/source/reference/lighttree.rst create mode 100644 docs/source/reference/lighttree.tree.rst create mode 100644 docs/source/reference/lighttree.utils.rst create mode 100644 docs/source/requirements.txt create mode 100644 docs/source/user-guide.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..a46ff57 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,32 @@ +# Makefile for Sphinx documentation + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + @rm -rf build + +api-doc: + @# T: notoc, e: separate module pages, f: rewrite, d: max-depth + @sphinx-apidoc -o source/reference ../lighttree -Tfe -d 8 + +build: + @mkdir -p build + @sphinx-build -b html source build + +generate: clean api-doc build + @# + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/__init__.py b/docs/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/CONTRIBUTING.md b/docs/source/CONTRIBUTING.md new file mode 100644 index 0000000..82212d4 --- /dev/null +++ b/docs/source/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing to lighttree +We want to make contributing to this project as easy and transparent as +possible. + +## Our Development Process +We use github to host code, to track issues and feature requests, as well as accept pull requests. + + +## Pull Requests +We actively welcome your pull requests. + +1. Fork the repo and create your branch from `master`. +2. If you've added code that should be tested, add tests. +3. If you've changed APIs, update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. + +## Any contributions you make will be under the MIT Software License +In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. +Feel free to contact the maintainers if that's a concern. + +## Issues +We use GitHub issues to track public bugs. Please ensure your description is +clear and has sufficient instructions to be able to reproduce the issue. + +## Report bugs using Github's [issues](https://github.com/leonardbinet/lighttree/issues) +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/leonardbinet/lighttree/issues/new); it's that easy! + +## Write bug reports with detail, background, and sample code + +**Great Bug Reports** tend to have: + +- A quick summary and/or background +- Steps to reproduce + - Be specific! + - Give sample code if you can. +- What you expected would happen +- What actually happens +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) + + +## License +By contributing, you agree that your contributions will be licensed under its MIT License. + +## References +This document was adapted from the open-source contribution guidelines of [briandk's gist](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62) diff --git a/docs/source/__init__.py b/docs/source/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a0e1929 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,188 @@ +# -*- 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('.')) + + +# -- Project information ----------------------------------------------------- + +project = u"lighttree" +copyright = u"2020, Léonard Binet" +author = u"Léonard Binet" + +# The short X.Y version +version = u"" +# The full version, including alpha/beta/rc tags +release = u"0.1" + + +# -- 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.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.viewcode", + "sphinx.ext.githubpages", + "recommonmark", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +source_suffix = [".rst", ".md"] + +# 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 = "sphinx_rtd_theme" + +# 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 = [] + +# 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 = "lighttreedoc" + + +# -- 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, "lighttree.tex", u"lighttree Documentation", u"Léonard Binet", "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, "lighttree", u"lighttree 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, + "lighttree", + u"lighttree Documentation", + author, + "lighttree", + ), +] + + +# -- 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} + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2d7cb9a --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,50 @@ +.. lighttree documentation master file + + +######### +lighttree +######### + +.. toctree:: + :hidden: + :maxdepth: 4 + + user-guide + API reference + Contributing + +**lighttree** is a Python package providing a simple interface to manipulate data with a tree structure. + +********** +Installing +********** + +**lighttree** can be installed with `pip `_:: + + $ pip install lighttree + +Alternatively, you can grab the latest source code from `GitHub `_:: + + $ git clone git://github.com/leonardbinet/lighttree.git + $ python setup.py install + +***** +Usage +***** + +The :doc:`user-guide` is the place to go to learn how to use the library and +accomplish common tasks (work in progress). + +The :doc:`reference/lighttree` documentation provides API-level documentation. + +******* +License +******* + +lighttree is made available under the MIT License. For more details, see `LICENSE.txt `_. + +************ +Contributing +************ + +We happily welcome contributions, please see :doc:`CONTRIBUTING` for details. diff --git a/docs/source/reference/lighttree.exceptions.rst b/docs/source/reference/lighttree.exceptions.rst new file mode 100644 index 0000000..c1ca448 --- /dev/null +++ b/docs/source/reference/lighttree.exceptions.rst @@ -0,0 +1,7 @@ +lighttree.exceptions module +=========================== + +.. automodule:: lighttree.exceptions + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/reference/lighttree.interactive.rst b/docs/source/reference/lighttree.interactive.rst new file mode 100644 index 0000000..83533fe --- /dev/null +++ b/docs/source/reference/lighttree.interactive.rst @@ -0,0 +1,7 @@ +lighttree.interactive module +============================ + +.. automodule:: lighttree.interactive + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/reference/lighttree.node.rst b/docs/source/reference/lighttree.node.rst new file mode 100644 index 0000000..18dc571 --- /dev/null +++ b/docs/source/reference/lighttree.node.rst @@ -0,0 +1,7 @@ +lighttree.node module +===================== + +.. automodule:: lighttree.node + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/reference/lighttree.rst b/docs/source/reference/lighttree.rst new file mode 100644 index 0000000..da8b5f4 --- /dev/null +++ b/docs/source/reference/lighttree.rst @@ -0,0 +1,22 @@ +lighttree package +================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 8 + + lighttree.exceptions + lighttree.interactive + lighttree.node + lighttree.tree + lighttree.utils + +Module contents +--------------- + +.. automodule:: lighttree + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/reference/lighttree.tree.rst b/docs/source/reference/lighttree.tree.rst new file mode 100644 index 0000000..1095d77 --- /dev/null +++ b/docs/source/reference/lighttree.tree.rst @@ -0,0 +1,7 @@ +lighttree.tree module +===================== + +.. automodule:: lighttree.tree + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/reference/lighttree.utils.rst b/docs/source/reference/lighttree.utils.rst new file mode 100644 index 0000000..310dca3 --- /dev/null +++ b/docs/source/reference/lighttree.utils.rst @@ -0,0 +1,7 @@ +lighttree.utils module +====================== + +.. automodule:: lighttree.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt new file mode 100644 index 0000000..f701512 --- /dev/null +++ b/docs/source/requirements.txt @@ -0,0 +1,2 @@ +recommonmark +sphinx_rtd_theme diff --git a/docs/source/user-guide.rst b/docs/source/user-guide.rst new file mode 100644 index 0000000..b0701ce --- /dev/null +++ b/docs/source/user-guide.rst @@ -0,0 +1,13 @@ +########## +User Guide +########## + + +.. note:: + + This is a work in progress. + + +********** +Principles +********** diff --git a/lighttree/tree.py b/lighttree/tree.py index f4c9379..59c8626 100644 --- a/lighttree/tree.py +++ b/lighttree/tree.py @@ -31,11 +31,20 @@ def __contains__(self, identifier): return identifier in self._nodes_map def get(self, nid): - """Get a node by its id.""" + """Get a node by its id. + :param nid: str, identifier of node to fetch + :rtype: lighttree.node.Node + """ self._ensure_present(nid) return self._nodes_map[nid] def list(self, id_in=None, depth_in=None, filter_=None): + """List nodes. + :param id_in: list of str, optional, filter nodes among provided identifiers + :param depth_in: list of int, optional, filter nodes whose depth in tree is among provided values + :param filter\_: function, optional, filtering function to apply to each node + :rtype: list of lighttree.node.Node + """ return [ node for nid, node in iteritems(self._nodes_map) @@ -45,7 +54,9 @@ def list(self, id_in=None, depth_in=None, filter_=None): ] def is_empty(self): - """Return whether tree is empty (contains nodes) or not.""" + """Return whether tree is empty (contains nodes) or not. + :rtype: bool + """ return self.root is None def _ensure_present(self, nid, defaults_to_root=False, allow_empty=False): @@ -97,6 +108,8 @@ def _clone_init(self, deep): >>> subtree = my_custom_tree.subtree() >>> subtree.tree_description "smart tree" + + :param: deep, boolean, in case of composition should its potential elements be deep copied or not. """ return self.__class__() @@ -405,8 +418,7 @@ def show( """Return tree structure in hierarchy style. :param nid: Node identifier from which tree traversal will start. If None tree root will be used - :param filter_: filter function performed on nodes. Nodes excluded from filter function nor their children - won't be displayed + :param filter_: filter function performed on nodes. Nodes excluded from filter function nor their children won't be displayed :param reverse: the ``reverse`` param for sorting :class:`Node` objects in the same level :param key: key used to order nodes of same parent :param reverse: reverse parameter applied at sorting @@ -414,6 +426,7 @@ def show( :param limit: int, truncate tree display to this number of lines :param kwargs: kwargs params passed to node ``line_repr`` method :rtype: unicode in python2, str in python3 + """ output = "" @@ -502,6 +515,7 @@ def merge(self, new_tree, nid=None, deep=False): """Merge "new_tree" on current tree by pasting its root children on current tree "nid" node. Consider the following trees: + >>> self.show() root ├── A @@ -514,8 +528,8 @@ def merge(self, new_tree, nid=None, deep=False): Merging new_tree on B node: - >>>self.merge(new_tree, 'B') - >>>self.show() + >>> self.merge(new_tree, 'B') + >>> self.show() root ├── A └── B @@ -525,6 +539,7 @@ def merge(self, new_tree, nid=None, deep=False): Note: if current tree is empty and nid is None, the new_tree root will be used as root on current tree. In all other cases new_tree root is not pasted. + """ if not isinstance(new_tree, self.__class__): raise ValueError(