Add tips for custom coordinates to docs

CHANGELOG.md

@@ -5,6 +5,8 @@ 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]
+### Added:
+- Docs: Tips for setting custom coordinates for plots.
 
 ## [0.23.1] - 2025-01-22
 ### Changed:

docs/others/custom_coordinates.md

@@ -0,0 +1,46 @@
+# Trees with Custom Coordinates
+
+> Topic: export
+
+Trees can be plotted with `root.plot()` for a simple matplotlib. For more sophisticated plots, it is recommended to
+export the tree to dot (supports pydot, graphviz), mermaid, or pillow. To set your own x- and y- coordinates, this
+utilises and builds on top of the existing pydot package.
+
+There are 3 ways to get the x- and y- coordinates for each node
+
+1. Use [reingold tilford](../bigtree/utils/plot.md#bigtree.utils.plot.reingold_tilford) function (fastest and easiest)
+2. Modify from the Reingold Tilford algorithm from (1)
+3. Use your custom coordinates
+
+Using these x- and y- coordinates, we can display it on a pydot plot using the `pos` node attribute. In the example
+below, we will make use of option (2) to generate our tree plot with custom coordinates.
+
+```python hl_lines="25"
+from bigtree import Node, clone_tree, list_to_tree, reingold_tilford, tree_to_dot
+
+# Create tree
+root = list_to_tree(["a/b/d", "a/c"])
+
+# Modify from the Reingold Tilford algorithm
+reingold_tilford(root)
+
+
+class CoordinateNode(Node):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.y = 2 * self.y  # example
+
+
+root_coordinate = clone_tree(root, CoordinateNode)
+
+
+# Export tree to dot (pydot)
+def node_pos(_node):
+    return {"pos": f"{_node.x},{_node.y}!"}
+
+
+graph = tree_to_dot(root_coordinate, node_attr=node_pos)
+graph.write_png("assets/docs/coordinate_tree.png", prog="neato")
+```
+
+![Custom Coordinate Tree Output](https://github.com/kayjan/bigtree/raw/master/assets/docs/coordinate_tree.png "Custom Coordinate Tree Output")

docs/others/list_dir.md

@@ -1,5 +1,7 @@
 # List Directory
 
+> Topic: construct
+
 To list directories recursively using bigtree, we can use the `glob` built-in Python package to extract a list of paths.
 
 ```python

docs/others/merging_trees.md

@@ -1,5 +1,7 @@
 # Merging Trees
 
+> Topic: modify
+
 To merge two separate trees into one, we can use the tree modify module.
 
 In this example, we are merging two trees that have similar node `Pictures`.

docs/others/nodes.md

@@ -1,6 +1,7 @@
 # Extending Nodes
 
 Nodes can be extended from `BaseNode` or `Node` class to have extended functionalities or add pre-/post-assign checks.
+
  - For example, `Node` class extends `BaseNode` and added the ``name`` functionality with pre-assign checks to ensure no duplicate path names.
 
 ## Population Node (add functionality/method/property)

docs/others/weighted_trees.md

@@ -1,5 +1,7 @@
 # Trees with Weighted Edges
 
+> Topic: export
+
 Edge weights should be defined in the child node for the parent-child edge since each node can only have one parent.
 
 We can simply add `weight` attribute to the `Node` class.

mkdocs.yml

@@ -54,12 +54,16 @@ nav:
         - bigtree/workflows/app_calendar.md
   - Others:
     - 💡 Tips and Tricks:
-      - others/remove_checks.md
-      - others/list_dir.md
-      - others/nodes.md
-      - others/merging_trees.md
-      - others/weighted_trees.md
-      - others/work_with_classes.md
+      - Optimise:
+        - others/remove_checks.md
+      - Node:
+        - others/nodes.md
+        - others/work_with_classes.md
+      - Tree:
+        - others/list_dir.md
+        - others/merging_trees.md
+        - others/weighted_trees.md
+        - others/custom_coordinates.md
 
 theme:
   name: material
@@ -86,6 +90,7 @@ theme:
     - navigation.tabs
     - navigation.tabs.sticky
     - navigation.top
+    - navigation.expand
     - navigation.indexes
     - navigation.sections
     - content.code.copy