Merge pull request #177 from kayjan/mkdocs

Mkdocs

Author: kayjan

.github/workflows/docs.yml

@@ -25,18 +25,13 @@ jobs:
     needs: setup
     steps:
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
       - name: Set up Python
         uses: actions/setup-python@v4
       - name: Install dependencies
         run: |
-          pip install -r docs_sphinx/requirements.txt
-      - name: Sphinx build
-        run: |
-          sphinx-build docs_sphinx/source docs_sphinx/build
+          pip install -r docs/requirements.txt
+          git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
       - name: Deploy to GH Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs_sphinx/build/
-          force_orphan: true
+        run: mkdocs gh-deploy

.gitignore

@@ -8,3 +8,4 @@ dist/
 *.DS_Store
 assets/docstr
 site/
+.cache

.readthedocs.yaml

@@ -12,10 +12,11 @@ build:
     python: "3.8"
 
 # Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs_sphinx/source/conf.py
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
 
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
-    - requirements: docs_sphinx/requirements.txt
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -1,11 +1,20 @@
-# Changelog
+# 🍂 Changelog
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.16.0] - 2023-01-28
+### Added
+- Misc: Documentation using mkdocs.
+### Changed
+- Misc: Markdown edit for README, CHANGELOG.
+- Misc: Docstring to indicate Examples, to indicate exceptions for BaseNode and DAGNode, simplify code for tree modification.
+### Fixed
+- Misc: Docstring bullet point alignment, images compatibility with markdown.
+
 ## [0.15.7] - 2023-01-26
 ### Added
 - Misc: Sphinx documentation to support mermaid markdown images, reflect CHANGELOG section, add more emojis.
@@ -473,7 +482,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Utility Iterator: Tree traversal methods.
 - Workflow To Do App: Tree use case with to-do list implementation.
 
-[Unreleased]: https://github.com/kayjan/bigtree/compare/0.15.7...HEAD
+[Unreleased]: https://github.com/kayjan/bigtree/compare/0.16.0...HEAD
+[0.16.0]: https://github.com/kayjan/bigtree/compare/0.15.7...0.16.0
 [0.15.7]: https://github.com/kayjan/bigtree/compare/0.15.6...0.15.7
 [0.15.6]: https://github.com/kayjan/bigtree/compare/0.15.5...0.15.6
 [0.15.5]: https://github.com/kayjan/bigtree/compare/0.15.4...0.15.5

README.md

@@ -22,7 +22,7 @@ Related Links:
   - [The Reingold Tilford Algorithm Explained, with Walkthrough](https://towardsdatascience.com/reingold-tilford-algorithm-explained-with-walkthrough-be5810e8ed93?sk=2db8e10398cee76c486c4b06b0b33322)
 - <div><p>If you want to support bigtree, <a href="https://www.buymeacoffee.com/kayjan"><img src="https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee" style="vertical-align:middle"></a></p></div>
 
-----
+-----
 
 ## Components
 There are 3 segments to Big Tree consisting of Tree, Binary Tree, and Directed Acyclic Graph (DAG) implementation.
@@ -87,7 +87,7 @@ Binary Node inherits from Node, so the components in Tree implementation are als
 3. [**➰ Traversing Binary Tree**](https://bigtree.readthedocs.io/en/latest/bigtree/utils/iterators.html)
    1. In-Order Traversal
 
---------
+-----
 
 For **Directed Acyclic Graph (DAG)** implementation, there are 4 main components.
 
@@ -103,46 +103,46 @@ For **Directed Acyclic Graph (DAG)** implementation, there are 4 main components
    1. Export to *list*, *dictionary*, or *pandas DataFrame*
    2. Export DAG to *dot* (can save to .dot, .png, .svg, .jpeg files)
 
-----
+-----
 
 ## Installation
 
-There are two ways to install `bigtree`, with pip (from PyPI) or conda (from conda-forge).
+There are two ways to install `bigtree`, with pip (recommended) or conda.
 
-### a) Installation with pip (recommended)
+### a) Installation with pip
 
 To install `bigtree`, run the following line in command prompt:
 
-```shell
+```console
 $ pip install bigtree
 ```
 
 If tree needs to use pandas methods, it requires additional dependencies.
 Run the following line in command prompt:
 
-```shell
+```console
 $ pip install 'bigtree[pandas]'
 ```
 
 If tree needs to be exported to image, it requires additional dependencies.
 Run the following lines in command prompt:
 
-```shell
+```console
 $ pip install 'bigtree[image]'
 $ brew install gprof2dot  # for MacOS
 $ conda install graphviz  # for Windows
 ```
 
 Alternatively, install all optional dependencies with the following line in command prompt:
 
-```shell
+```console
 $ pip install 'bigtree[all]'
 ```
 
 ### b) Installation with conda
 
 To install `bigtree` with conda, run the following line in command prompt:
 
-```shell
+```console
 $ conda install -c conda-forge bigtree
 ```

bigtree/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.15.7"
+__version__ = "0.16.0"
 
 from bigtree.binarytree.construct import list_to_binarytree
 from bigtree.dag.construct import dataframe_to_dag, dict_to_dag, list_to_dag
@@ -75,4 +75,4 @@
 from bigtree.workflows.app_calendar import Calendar
 from bigtree.workflows.app_todo import AppToDo
 
-sphinx_versions = ["latest", "0.15.7", "0.14.8"]
+sphinx_versions = ["latest", "0.16.0", "0.15.7", "0.14.8"]

bigtree/binarytree/construct.py

@@ -10,24 +10,25 @@ def list_to_binarytree(
 ) -> BinaryNode:
     """Construct tree from a list of numbers (int or float) in heapq format.
 
-    >>> from bigtree import list_to_binarytree, tree_to_dot
-    >>> nums_list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
-    >>> root = list_to_binarytree(nums_list)
-    >>> root.show()
-    1
-    ├── 2
-    │   ├── 4
-    │   │   ├── 8
-    │   │   └── 9
-    │   └── 5
-    │       └── 10
-    └── 3
-        ├── 6
-        └── 7
-    >>> graph = tree_to_dot(root, node_colour="gold")
-    >>> graph.write_png("assets/construct_binarytree.png")
-
-    .. image:: https://github.com/kayjan/bigtree/raw/master/assets/construct_binarytree.png
+    Examples:
+        >>> from bigtree import list_to_binarytree, tree_to_dot
+        >>> nums_list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        >>> root = list_to_binarytree(nums_list)
+        >>> root.show()
+        1
+        ├── 2
+        │   ├── 4
+        │   │   ├── 8
+        │   │   └── 9
+        │   └── 5
+        │       └── 10
+        └── 3
+            ├── 6
+            └── 7
+        >>> graph = tree_to_dot(root, node_colour="gold")
+        >>> graph.write_png("assets/construct_binarytree.png")
+
+        ![Sample Binary Tree](https://github.com/kayjan/bigtree/raw/master/assets/construct_binarytree.png)
 
     Args:
         heapq_list (List[int]): list containing integer node names, ordered in heapq fashion

bigtree/dag/construct.py

@@ -21,11 +21,12 @@ def list_to_dag(
     """Construct DAG from list of tuples containing parent-child names.
     Note that node names must be unique.
 
-    >>> from bigtree import list_to_dag, dag_iterator
-    >>> relations_list = [("a", "c"), ("a", "d"), ("b", "c"), ("c", "d"), ("d", "e")]
-    >>> dag = list_to_dag(relations_list)
-    >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
-    [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
+    Examples:
+        >>> from bigtree import list_to_dag, dag_iterator
+        >>> relations_list = [("a", "c"), ("a", "d"), ("b", "c"), ("c", "d"), ("d", "e")]
+        >>> dag = list_to_dag(relations_list)
+        >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
+        [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
 
     Args:
         relations (List[Tuple[str, str]]): list containing tuple of parent-child names
@@ -52,17 +53,18 @@ def dict_to_dag(
     name, and attribute value.
     Note that node names must be unique.
 
-    >>> from bigtree import dict_to_dag, dag_iterator
-    >>> relation_dict = {
-    ...     "a": {"step": 1},
-    ...     "b": {"step": 1},
-    ...     "c": {"parents": ["a", "b"], "step": 2},
-    ...     "d": {"parents": ["a", "c"], "step": 2},
-    ...     "e": {"parents": ["d"], "step": 3},
-    ... }
-    >>> dag = dict_to_dag(relation_dict, parent_key="parents")
-    >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
-    [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
+    Examples:
+        >>> from bigtree import dict_to_dag, dag_iterator
+        >>> relation_dict = {
+        ...     "a": {"step": 1},
+        ...     "b": {"step": 1},
+        ...     "c": {"parents": ["a", "b"], "step": 2},
+        ...     "d": {"parents": ["a", "c"], "step": 2},
+        ...     "e": {"parents": ["d"], "step": 3},
+        ... }
+        >>> dag = dict_to_dag(relation_dict, parent_key="parents")
+        >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
+        [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
 
     Args:
         relation_attrs (Dict[str, Any]): dictionary containing node, node parents, and node attribute information,
@@ -103,27 +105,28 @@ def dataframe_to_dag(
     """Construct DAG from pandas DataFrame.
     Note that node names must be unique.
 
-    `child_col` and `parent_col` specify columns for child name and parent name to construct DAG.
-    `attribute_cols` specify columns for node attribute for child name
-    If columns are not specified, `child_col` takes first column, `parent_col` takes second column, and all other
-    columns are `attribute_cols`.
-
-    >>> import pandas as pd
-    >>> from bigtree import dataframe_to_dag, dag_iterator
-    >>> relation_data = pd.DataFrame([
-    ...     ["a", None, 1],
-    ...     ["b", None, 1],
-    ...     ["c", "a", 2],
-    ...     ["c", "b", 2],
-    ...     ["d", "a", 2],
-    ...     ["d", "c", 2],
-    ...     ["e", "d", 3],
-    ... ],
-    ...     columns=["child", "parent", "step"]
-    ... )
-    >>> dag = dataframe_to_dag(relation_data)
-    >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
-    [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
+    - `child_col` and `parent_col` specify columns for child name and parent name to construct DAG.
+    - `attribute_cols` specify columns for node attribute for child name.
+    - If columns are not specified, `child_col` takes first column, `parent_col` takes second column, and all other
+        columns are `attribute_cols`.
+
+    Examples:
+        >>> import pandas as pd
+        >>> from bigtree import dataframe_to_dag, dag_iterator
+        >>> relation_data = pd.DataFrame([
+        ...     ["a", None, 1],
+        ...     ["b", None, 1],
+        ...     ["c", "a", 2],
+        ...     ["c", "b", 2],
+        ...     ["d", "a", 2],
+        ...     ["d", "c", 2],
+        ...     ["e", "d", 3],
+        ... ],
+        ...     columns=["child", "parent", "step"]
+        ... )
+        >>> dag = dataframe_to_dag(relation_data)
+        >>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
+        [('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]
 
     Args:
         data (pd.DataFrame): data containing path and node attribute information