From be5e33625a02d486afb2f6d0a19c8cb1e5293986 Mon Sep 17 00:00:00 2001
From: Will Robertson <wspr81@gmail.com>
Date: Mon, 25 Mar 2024 21:50:58 +1030
Subject: [PATCH] work on doc

---
 ausankey/ausankey.py        |  2 +-
 docs/index.md               | 56 ++++++++++++++++++++++++++++++++++++-
 docs/sankey_doc_examples.py | 37 ++++++++++++++++++++++++
 3 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/ausankey/ausankey.py b/ausankey/ausankey.py
index 2f3dbc3..93503a4 100644
--- a/ausankey/ausankey.py
+++ b/ausankey/ausankey.py
@@ -36,7 +36,7 @@ def sankey(
     frame_color=None,
     label_dict=None,
     label_width=0,
-    label_gap=0.01,
+    label_gap=0.02,
     label_loc=None,
     label_font=None,
     flow_lw=1,
diff --git a/docs/index.md b/docs/index.md
index b58a0ae..03536a7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -93,7 +93,7 @@ sky.sankey(data,color_dict=color_dict)
 ```
 ![Image with options](fruits_colordict.png)
 
-The opacity of the flows can be customised:
+The opacity of the flows and nodes can be customised with `flow_alpha` and `node_alpha` respectively:
 ```
 sky.sankey(data,flow_alpha=0.3)
 ```
@@ -122,6 +122,7 @@ sky.sankey(data,sort=“none”)
 ```
 ![Image with options](fruits_sort_none.png)
 
+
 ## Labels
 
 If the data is generated externally it may not be convenient to edit the label text in the source. The typeset labels can be specified using a dictionary of lookup strings:
@@ -185,6 +186,41 @@ sky.sankey(data,
 ```
 ![Image with options](fruits_titles_outer.png)
 
+
+## Fonts
+
+The font family, font colour, and font size can be set globally:
+```
+sky.sankey(data,
+    titles=[“Summer”, “Winter”],
+    fontsize=15,
+    fontfamily=“serif”,
+    fontcolor=“red”,
+)
+```
+![Image with options](fruits_fonts.png)
+
+These options do not use `snake_case` for consistency with their underlying Matplotlib options.
+Further font options can be passed through directly via the `label_font` and `title_font` options, which override the settings above.
+
+For example:
+```
+sky.sankey(
+  data3,
+  titles    = [“Stage 0”,”Stage 1”,”Stage 2”],
+  title_font = {
+      “color”: “red”, 
+      “fontsize”: 14, 
+      “fontweight”: “bold”,
+  },
+  label_font = {“color”: “blue”},
+)
+```
+![Image with options](data3_fonts_fancy.png)
+
+Refer to [Matplotlib documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.text.html) for available options.
+
+
 ## Vertical Alignment
 
 The vertical alignment of the diagram can be  `"top"`, `"bottom"`, or `"center"`:
@@ -211,6 +247,24 @@ sky.sankey(data,
 ```
 ![Image with options](fruits_frame_color.png)
 
+
+## Edges
+
+Lines around the edges of the nodes and/or flows can be specified as follows. 
+```
+sky.sankey(data3,
+    node_width = 0.1,
+    node_alpha = 0.6,
+    flow_alpha = 0.3,
+    node_edge = True,
+    flow_edge = True,
+    node_lw = 2,
+    flow_lw = 1,
+    )
+```
+![Image with options](frame3_edge.png)
+
+
 ## Spacing
 
 A number of parameters can be set to customise the spacing and layout of the diagram. These parameters are normalised against the diagram height or width according to which direction they are oriented. 
diff --git a/docs/sankey_doc_examples.py b/docs/sankey_doc_examples.py
index 0c948b3..675062f 100644
--- a/docs/sankey_doc_examples.py
+++ b/docs/sankey_doc_examples.py
@@ -82,6 +82,30 @@
 plt.show()
 plt.savefig("fruits_titles_outer.png")
 
+plt.figure()
+sky.sankey(data,
+    titles=["Summer", "Winter"],
+    fontsize=15,
+    fontfamily="serif",
+    fontcolor="red",
+)
+plt.show()
+plt.savefig("fruits_fonts.png")
+
+plt.figure(dpi=600)
+sky.sankey(
+  data3,
+  titles    = ["Stage 0","Stage 1","Stage 2"],
+  title_font = {
+      "color": "red", 
+      "fontsize": 14, 
+      "fontweight": "bold",
+  },
+  label_font = {"color": "blue"},
+)
+plt.show()
+plt.savefig("data3_fonts_fancy.png")
+
 plt.figure()
 sky.sankey(data, valign="center")
 plt.show()
@@ -198,3 +222,16 @@
 )
 
 plt.savefig("frame3_many.png")
+
+
+plt.figure(dpi=600)
+sky.sankey(data3,
+    node_width = 0.1,
+    node_alpha = 0.6,
+    flow_alpha = 0.3,
+    node_edge = True,
+    flow_edge = True,
+    node_lw = 2,
+    flow_lw = 1,
+    )
+plt.savefig("frame3_edge.png")