Skip to content

Commit 711f8cb

Browse files
kayjankayjan
authored
Improve docs (#439)
* docs: enhance getting started docs * docs: enhance bigtree docs
1 parent beecc6b commit 711f8cb

File tree

12 files changed

+182
-152
lines changed

12 files changed

+182
-152
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77
## [Unreleased]
88
### Added:
99
- Misc: Citation file.
10+
### Changed:
11+
- Docs: Clean up and make more succinct.
1012

1113
## [1.3.1] - 2026-02-14
1214
### Added:

‎bigtree/_plugins.py‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,17 @@ def register_tree_plugins() -> None:
113113
"to_pillow": export.tree_to_pillow,
114114
"to_mermaid": export.tree_to_mermaid,
115115
"to_vis": export.tree_to_vis,
116+
# Iterator methods
117+
"preorder_iter": iterators.preorder_iter,
118+
"postorder_iter": iterators.postorder_iter,
119+
"levelorder_iter": iterators.levelorder_iter,
120+
"levelordergroup_iter": iterators.levelordergroup_iter,
121+
"zigzag_iter": iterators.zigzag_iter,
122+
"zigzaggroup_iter": iterators.zigzaggroup_iter,
123+
# Modify methods
124+
"shift_nodes": modify.shift_nodes,
125+
"copy_nodes": modify.copy_nodes,
126+
"shift_and_replace_nodes": modify.shift_and_replace_nodes,
116127
# Query methods
117128
"query": query.query_tree,
118129
# Search methods
@@ -130,17 +141,6 @@ def register_tree_plugins() -> None:
130141
"find_children": search.find_children,
131142
"find_child": search.find_child,
132143
"find_child_by_name": search.find_child_by_name,
133-
# Iterator methods
134-
"preorder_iter": iterators.preorder_iter,
135-
"postorder_iter": iterators.postorder_iter,
136-
"levelorder_iter": iterators.levelorder_iter,
137-
"levelordergroup_iter": iterators.levelordergroup_iter,
138-
"zigzag_iter": iterators.zigzag_iter,
139-
"zigzaggroup_iter": iterators.zigzaggroup_iter,
140-
# Modify methods
141-
"shift_nodes": modify.shift_nodes,
142-
"copy_nodes": modify.copy_nodes,
143-
"shift_and_replace_nodes": modify.shift_and_replace_nodes,
144144
}
145145
)
146146
Tree.register_plugins(

‎bigtree/binarytree/binarytree.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ class BinaryTree(Tree):
99
"""
1010
BinaryTree wraps around BinaryNode class to provide a quick, intuitive, Pythonic API for
1111
12-
* Construction with dataframe, dictionary, list, or string
13-
* Export to dataframe, dictionary, list, string, or images
14-
* Helper methods for cloning, pruning, getting tree diff
15-
* Query and Search methods to find one or more Nodes
12+
* Construction with dataframe, dictionary, list, or string
13+
* Export to dataframe, dictionary, list, string, or images
14+
* Query and Search methods to find one or more Nodes
15+
* Helper methods for cloning, pruning, getting tree diff
1616
1717
Do refer to the various modules respectively on the keyword parameters.
1818
"""

‎bigtree/dag/dag.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ class DAG:
1212
"""
1313
DAG wraps around DAGNode class to provide a quick, intuitive, Pythonic API for
1414
15-
* Construction with dataframe, dictionary, or list
16-
* Export to dataframe, dictionary, list, or images
17-
* Iterator methods to parse dag
15+
* Construction with dataframe, dictionary, or list
16+
* Export to dataframe, dictionary, list, or images
17+
* Iterator methods to parse dag
1818
1919
Do refer to the various modules respectively on the keyword parameters.
2020
"""

‎bigtree/tree/tree.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,13 @@ class Tree:
2222
"""
2323
Tree wraps around Node class to provide a quick, intuitive, Pythonic API for
2424
25-
* Construction with dataframe, dictionary, list, or string
26-
* Export to dataframe, dictionary, list, string, or images
27-
* Helper methods for cloning, pruning, getting subtree and tree diff
28-
* Iterator methods to parse tree
29-
* Query and Search methods to find one or more Nodes
30-
* Plot methods
25+
* Construction with dataframe, dictionary, list, or string
26+
* Export to dataframe, dictionary, list, string, or images
27+
* Iterator methods to parse tree
28+
* Modify methods for shifting and copying nodes
29+
* Query and Search methods to find one or more Nodes
30+
* Helper methods for cloning, pruning, getting subtree and tree diff
31+
* Plot methods
3132
3233
Do refer to the various modules respectively on the keyword parameters.
3334
"""

‎docs/bigtree/tree/construct.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,19 @@ Construct Tree from list, dictionary, and pandas/polars DataFrame.
1010

1111
To decide which method to use, consider your data type and data values.
1212

13-
| Construct tree from | Using full path | Using parent-child relation | Using notation | Add node attributes |
14-
|---------------------|---------------------|--------------------------------------------------|------------------|------------------------------------------------------|
15-
| String | `str_to_tree` | NA | `newick_to_tree` | No (for `str_to_tree`)<br>Yes (for `newick_to_tree`) |
16-
| List | `list_to_tree` | `list_to_tree_by_relation` | NA | No |
17-
| Dictionary | `dict_to_tree` | `nested_dict_to_tree`, `nested_dict_key_to_tree` | NA | Yes |
18-
| pandas DataFrame | `dataframe_to_tree` | `dataframe_to_tree_by_relation` | NA | Yes |
19-
| polars DataFrame | `polars_to_tree` | `polars_to_tree_by_relation` | NA | Yes |
20-
| Interactive UI | NA | `render_tree` | NA | No |
21-
22-
| Construct tree from | Notation | Add node attributes |
23-
|---------------------|----------------|-----------------------|
24-
| rich Tree | `rich_to_tree` | Only style attributes |
13+
| Construct tree from | Using full path | Using parent-child relation | Add node attributes |
14+
|---------------------|---------------------|--------------------------------------------------|---------------------|
15+
| List | `list_to_tree` | `list_to_tree_by_relation` | No |
16+
| Dictionary | `dict_to_tree` | `nested_dict_to_tree`, `nested_dict_key_to_tree` | Yes |
17+
| pandas DataFrame | `dataframe_to_tree` | `dataframe_to_tree_by_relation` | Yes |
18+
| polars DataFrame | `polars_to_tree` | `polars_to_tree_by_relation` | Yes |
19+
| Interactive UI | NA | `render_tree` | No |
20+
21+
| Construct tree from | Notation | Add node attributes |
22+
|---------------------|------------------|-----------------------|
23+
| String | `str_to_tree` | No |
24+
| Newick string | `newick_to_tree` | Yes |
25+
| rich Tree | `rich_to_tree` | Only style attributes |
2526

2627
## Tree Add Attributes Methods
2728

‎docs/bigtree/tree/tree.md‎

Lines changed: 37 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,18 @@ Construct Tree from list, dictionary, and pandas/polars DataFrame.
1717
To decide which method to use, consider your data type and data values. Construction methods are implemented as class
1818
methods.
1919

20-
| Construct tree from | Using full path | Using parent-child relation | Using notation | Add node attributes |
21-
|---------------------|-----------------------|------------------------------------------------------|--------------------|----------------------------------------------------------|
22-
| String | `Tree.from_str` | NA | `Tree.from_newick` | No (for `Tree.from_str`)<br>Yes (for `Tree.from_newick`) |
23-
| List | `Tree.from_list` | `Tree.from_list_relation` | NA | No |
24-
| Dictionary | `Tree.from_dict` | `Tree.from_nested_dict`, `Tree.from_nested_dict_key` | NA | Yes |
25-
| pandas DataFrame | `Tree.from_dataframe` | `Tree.from_dataframe_relation` | NA | Yes |
26-
| polars DataFrame | `Tree.from_polars` | `Tree.from_polars_relation` | NA | Yes |
27-
28-
| Construct tree from | Notation | Add node attributes |
29-
|---------------------|---------------------|-----------------------|
30-
| rich Tree | `Tree.from_rich` | Only style attributes |
20+
| Construct tree from | Using full path | Using parent-child relation | Add node attributes |
21+
|---------------------|-----------------------|------------------------------------------------------|---------------------|
22+
| List | `Tree.from_list` | `Tree.from_list_relation` | No |
23+
| Dictionary | `Tree.from_dict` | `Tree.from_nested_dict`, `Tree.from_nested_dict_key` | Yes |
24+
| pandas DataFrame | `Tree.from_dataframe` | `Tree.from_dataframe_relation` | Yes |
25+
| polars DataFrame | `Tree.from_polars` | `Tree.from_polars_relation` | Yes |
26+
27+
| Construct tree from | Notation | Add node attributes |
28+
|---------------------|--------------------|-----------------------|
29+
| String | `Tree.from_str` | No |
30+
| Newick string | `Tree.from_newick` | Yes |
31+
| rich Tree | `Tree.from_rich` | Only style attributes |
3132

3233
To add attributes to an existing tree,
3334

@@ -58,16 +59,25 @@ Export Tree to list, dictionary, pandas/polars DataFrame, and various formats.
5859
| Mermaid Markdown (for .md) | `to_mermaid` |
5960
| Visualization | `to_vis` |
6061

61-
## Tree Helper Methods
62+
## Tree Iterator Methods
6263

63-
Helper functions that can come in handy. Helper methods will return a separate Tree-type object.
64+
Iterator methods will return Node-type object(s).
6465

65-
| Description | Method |
66-
|---------------|--------------------------|
67-
| Clone tree | `clone` |
68-
| Get subtree | `subtree` |
69-
| Prune tree | `prune` |
70-
| Compare trees | `diff_dataframe`, `diff` |
66+
| Data Structure | Algorithm | Description |
67+
|----------------|-------------------------------------------|-------------------------|
68+
| Tree | `preorder_iter` | Depth-First Search, NLR |
69+
| Tree | `postorder_iter` | Depth-First Search, LRN |
70+
| Tree | `levelorder_iter`, `levelordergroup_iter` | Breadth-First Search |
71+
| Tree | `zigzag_iter`, `zigzaggroup_iter` | Breadth-First Search |
72+
73+
## Tree Modify Methods
74+
75+
Modification functions can shift and/or copy nodes within the same tree.
76+
77+
| Description | Method |
78+
|---------------|-------------------------------------------|
79+
| Shift node(s) | `shift_nodes` / `shift_and_replace_nodes` |
80+
| Copy node(s) | `copy_nodes` |
7181

7282
## Tree Query and Search Methods
7383

@@ -81,16 +91,16 @@ Query and search to find nodes. These methods will return Node-type object(s).
8191
| Node path | `find_path`, `find_full_path`, `find_relative_path` | `find_paths`, `find_relative_paths` |
8292
| Node attributes | `find_attr` | `find_attrs` |
8393

84-
## Iterator Methods
94+
## Tree Helper Methods
8595

86-
Iterator methods will return Node-type object(s).
96+
Helper functions that can come in handy. Helper methods will return a separate Tree-type object.
8797

88-
| Data Structure | Algorithm | Description |
89-
|----------------|-------------------------------------------|-------------------------|
90-
| Tree | `preorder_iter` | Depth-First Search, NLR |
91-
| Tree | `postorder_iter` | Depth-First Search, LRN |
92-
| Tree | `levelorder_iter`, `levelordergroup_iter` | Breadth-First Search |
93-
| Tree | `zigzag_iter`, `zigzaggroup_iter` | Breadth-First Search |
98+
| Description | Method |
99+
|---------------|--------------------------|
100+
| Clone tree | `clone` |
101+
| Get subtree | `subtree` |
102+
| Prune tree | `prune` |
103+
| Compare trees | `diff_dataframe`, `diff` |
94104

95105
-----
96106
::: bigtree.tree.tree

‎docs/gettingstarted/demo/binarytree.md‎

Lines changed: 26 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -46,35 +46,34 @@ from bigtree import BinaryTree
4646

4747
nums_list = [1, 2, 3, 4, 5, 6, 7, 8]
4848
tree = BinaryTree.from_heapq_list(nums_list)
49-
tree.show()
50-
# 1
51-
# ├── 2
52-
# │ ├── 4
53-
# │ │ └── 8
54-
# │ └── 5
55-
# └── 3
56-
# ├── 6
57-
# └── 7
49+
tree.hshow()
50+
# ┌─ 8
51+
# ┌─ 4 ─┤
52+
# ┌─ 2 ─┤ └─
53+
# ─ 1 ─┤ └─ 5
54+
# │ ┌─ 6
55+
# └─ 3 ─┤
56+
# └─ 7
5857
```
5958

6059
## Traverse Binary Tree
6160

6261
In addition to the traversal methods in the usual tree, binary tree includes in-order traversal method.
6362

64-
```python hl_lines="15 18 21 24 27 30 33"
63+
```python hl_lines="15 18 21 24 27-30 33 36-39"
6564
from bigtree import BinaryTree
6665

6766
nums_list = [1, 2, 3, 4, 5, 6, 7, 8]
6867
tree = tree.from_heapq_list(nums_list)
69-
tree.show()
70-
# 1
71-
# ├── 2
72-
# │ ├── 4
73-
# │ │ └── 8
74-
# │ └── 5
75-
# └── 3
76-
# ├── 6
77-
# └── 7
68+
tree.hshow()
69+
# ┌─ 8
70+
# ┌─ 4 ─┤
71+
# ┌─ 2 ─┤ └─
72+
# ─ 1 ─┤ └─ 5
73+
# │ ┌─ 6
74+
# └─ 3 ─┤
75+
# └─ 7
76+
7877

7978
[node.node_name for node in tree.inorder_iter()]
8079
# ['8', '4', '2', '5', '1', '6', '3', '7']
@@ -88,12 +87,18 @@ tree.show()
8887
[node.node_name for node in tree.levelorder_iter()]
8988
# ['1', '2', '3', '4', '5', '6', '7', '8']
9089

91-
[[node.node_name for node in node_group] for node_group in tree.levelordergroup_iter()]
90+
[
91+
[node.node_name for node in node_group]
92+
for node_group in tree.levelordergroup_iter()
93+
]
9294
# [['1'], ['2', '3'], ['4', '5', '6', '7'], ['8']]
9395

9496
[node.node_name for node in tree.zigzag_iter()]
9597
# ['1', '3', '2', '4', '5', '6', '7', '8']
9698

97-
[[node.node_name for node in node_group] for node_group in tree.zigzaggroup_iter()]
99+
[
100+
[node.node_name for node in node_group]
101+
for node_group in tree.zigzaggroup_iter()
102+
]
98103
# [['1'], ['3', '2'], ['4', '5', '6', '7'], ['8']]
99104
```

‎docs/gettingstarted/demo/dag.md‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -134,12 +134,11 @@ Below are the tables of attributes available to `DAGNode` class.
134134

135135
Below is the table of operations available to `DAGNode` class.
136136

137-
| Operations | Code | Returns |
138-
|---------------------------------------|-----------------------------------------------|----------------------------------------------------------------------------|
139-
| Get node information | `dag.describe(exclude_prefix="_")` | [('name', 'd')] |
140-
| Find path(s) from one node to another | `node_a.go_to(dag)` | [[DAGNode(a, ), DAGNode(c, ), DAGNode(d, )], [DAGNode(a, ), DAGNode(d, )]] |
141-
| Add child to node | `node_a.append(DAGNode("j"))` | DAGNode(a, ) |
142-
| Add multiple children to node | `node_a.extend([DAGNode("k"), DAGNode("l")])` | DAGNode(a, ) |
143-
| Set attribute(s) | `dag.set_attrs({"description": "dag-tag"})` | None |
144-
| Get attribute | `dag.get_attr("description")` | 'dag-tag' |
145-
| Copy DAG | `dag.copy()` | None |
137+
| Operations | Code | Returns |
138+
|---------------------------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------|
139+
| Get node information | `dag.describe(exclude_prefix="_")` | [('name', 'd')] |
140+
| Find path(s) from one node to another | `node_a.go_to(dag)` | [[DAGNode(a, ), DAGNode(c, ), DAGNode(d, )], [DAGNode(a, ), DAGNode(d, )]] |
141+
| Add one or more children to node | `node_a.append(DAGNode("j"))` / `node_a.extend([DAGNode("k"), DAGNode("l")])` | DAGNode(a, ) |
142+
| Set attribute(s) | `dag.set_attrs({"description": "dag-tag"})` | None |
143+
| Get attribute | `dag.get_attr("description")` | 'dag-tag' |
144+
| Copy DAG | `dag.copy()` | None |

0 commit comments

Comments
 (0)