Merge pull request #316 from kayjan/bugfix/docstring

Add docstring comment to prefer node_name over name

CHANGELOG.md

@@ -5,6 +5,11 @@ 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:
+- Tree Export: Mermaid diagram to include theme.
+### Fixed:
+- Misc: Doctest for docstrings, docstring to indicate usage prefers `node_name` to `name`.
+- Tree Export: Mermaid diagram title to add newline.
 
 ## [0.22.1] - 2024-11-03
 ### Added:

bigtree/node/node.py

@@ -61,7 +61,9 @@ class Node(basenode.BaseNode):
 
     Get `Node` configuration
 
-    1. ``node_name``: Get node name, without accessing `name` directly
+    1. ``node_name``: Get node name, without accessing `name` directly.
+        This is the preferred way to access node name as `node_name` is
+        immutable, whereas `name` is mutable.
     2. ``path_name``: Get path name from root, separated by `sep`
 
     **Node Methods**

bigtree/tree/export.py

@@ -1430,6 +1430,7 @@ def get_list_of_text_dimensions(
 def tree_to_mermaid(
     tree: T,
     title: str = "",
+    theme: Optional[str] = None,
     rankdir: str = "TB",
     line_shape: str = "basis",
     node_colour: str = "",
@@ -1447,6 +1448,7 @@ def tree_to_mermaid(
 
     Parameters for customizations that apply to entire flowchart include:
         - Title, `title`
+        - Theme, `theme`
         - Layout direction, `rankdir`
         - Line shape or curvature, `line_shape`
         - Fill colour of nodes, `node_colour`
@@ -1465,6 +1467,13 @@ def tree_to_mermaid(
 
     **Accepted Parameter Values**
 
+    Possible theme:
+        - default
+        - neutral: great for black and white documents
+        - dark: great for dark-mode
+        - forest: shades of geen
+        - base: theme that can be modified, use it for customizations
+
     Possible rankdir:
         - `TB`: top-to-bottom
         - `BT`: bottom-to-top
@@ -1546,6 +1555,7 @@ def tree_to_mermaid(
         >>> graph = tree_to_mermaid(
         ...     root,
         ...     title="Mermaid Diagram",
+        ...     theme="forest",
         ...     node_shape_attr="node_shape",
         ...     edge_label="edge_label",
         ...     edge_arrow_attr="edge_arrow",
@@ -1556,7 +1566,7 @@ def tree_to_mermaid(
         ---
         title: Mermaid Diagram
         ---
-        %%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
+        %%{ init: { 'flowchart': { 'curve': 'basis' }, 'theme': 'forest' } }%%
         flowchart TB
         0{"a"} ==>|Child 1| 0-0("b")
         0-0 --> 0-0-0("d"):::class0-0-0
@@ -1593,12 +1603,15 @@ def tree_to_mermaid(
     """
     from bigtree.tree.helper import clone_tree
 
+    themes = constants.MermaidConstants.THEMES
     rankdirs = constants.MermaidConstants.RANK_DIR
     line_shapes = constants.MermaidConstants.LINE_SHAPES
     node_shapes = constants.MermaidConstants.NODE_SHAPES
     edge_arrows = constants.MermaidConstants.EDGE_ARROWS
 
     # Assertions
+    if theme:
+        assertions.assert_str_in_list("theme", theme, themes)
     assertions.assert_str_in_list("rankdir", rankdir, rankdirs)
     assertions.assert_key_in_dict("node_shape", node_shape, node_shapes)
     assertions.assert_str_in_list("line_shape", line_shape, line_shapes)
@@ -1609,8 +1622,9 @@ def tree_to_mermaid(
     style_template = "classDef {style_name} {style}"
 
     # Content
+    theme_mermaid = f", 'theme': '{theme}'" if theme else ""
     title = f"---\ntitle: {title}\n---\n" if title else ""
-    line_style = f"%%{{ init: {{ 'flowchart': {{ 'curve': '{line_shape}' }} }} }}%%"
+    line_style = f"%%{{ init: {{ 'flowchart': {{ 'curve': '{line_shape}' }}{theme_mermaid} }} }}%%"
     styles = []
     flows = []
 

bigtree/utils/constants.py

@@ -171,6 +171,7 @@ def __post_init__(self) -> None:
 
 
 class MermaidConstants:
+    THEMES: List[str] = ["default", "neutral", "dark", "forest", "base"]
     RANK_DIR: List[str] = ["TB", "BT", "LR", "RL"]
     LINE_SHAPES: List[str] = [
         "basis",