Update document

docs/examples.rst

@@ -6,8 +6,8 @@ Several examples are shown below by topics, which covers all parameters that PyW
 .. toctree::
    :maxdepth: 2
 
-   examples/basic_examples
-   examples/plot_on_existed_axis
+   examples/formats_of_values
+   examples/figure_and_axis_manipulation
    examples/value_scaling_and_auto_sizing
    examples/title_label_legend
    examples/block_colors

docs/examples/figure_and_axis_manipulation.md

@@ -0,0 +1,55 @@
+# Figure and Axis Manipulation
+
+## Update plot with returned Figure and Axes
+
+You are free to modify the figure generated by `Waffle` class. 
+You may get all axes in the figure through property [Figure.axes](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.axes), and modify them through the list.
+
+For example, if you would like to remove the auto-generated legend, and save the figure into a file, you can update the axis through `axes` property and then call `savefig()` with the returned figure:
+
+```python
+fig = plt.figure(
+    FigureClass=Waffle,
+    rows=5,
+    columns=10,
+    values={'Cat1': 30, 'Cat2': 16, 'Cat3': 4},
+)
+
+# Remove legend
+fig.axes[0].get_legend().remove()
+
+# Save the figure into a file
+fig.savefig("my_plot.png")
+```
+
+---
+
+## Make Waffle on Existed Axis
+
+Sometimes you might have figure and axis created already, and you would like to plot waffle chart on top of 
+it, without creating a new figure. In this case, you may use `Waffle.make_waffle()` function, which accepts axis `ax` and other arguments available in `Waffle`.
+
+> **_NOTE:_** `Waffle.make_waffle()` is a classmethod, and you should call it without creating a new `Waffle` instance.
+
+> **_NOTE:_** The only argument that is available in Waffle but unsupported in `Waffle.make_waffle()` is `plots`, since it only accept one axis. Thus, this function can only generate waffle chart in a single plot.
+
+Below is an example showing that you may create and modify the figure and axis first, and then pass the axis to `Waffle.make_waffle()` for waffle chart plotting.
+
+```python
+fig = plt.figure()
+ax = fig.add_subplot(111)
+
+# Modify existed axis
+ax.set_title("Axis Title")
+ax.set_aspect(aspect="equal")
+
+Waffle.make_waffle(
+    ax=ax,  # pass axis to make_waffle
+    rows=5, 
+    columns=10, 
+    values=[30, 16, 4], 
+    title={"label": "Waffle Title", "loc": "left"}
+)
+```
+
+<img class="img_middle" alt="With list values" src="https://raw.githubusercontent.com/gyli/PyWaffle/master/examples/docs/plot_on_existed_axis.svg?sanitize=true">

docs/examples/basic_examples.md → docs/examples/formats_of_values.md

@@ -1,10 +1,8 @@
-# Basic Examples
+# Formats of Values
 
 This is a simple example to plot a 5-row, 10-column waffle chart. The three values are plotted as blocks directly, 
 and the blocks number matches the numbers in `values`, because the sum of `values` equals to total block number (`rows * columns`).
 
-> **_NOTE:_** One of the parameter `rows` and `columns` is redundant in this case, since both of the chart size and value sum are 50. So, either one of `rows` and `columns` could be omitted, and it can still be calculated through value sum automatically. See [Auto-sizing](value_scaling_and_auto_sizing.md) for more details. 
-
 ```python
 import matplotlib.pyplot as plt
 from pywaffle import Waffle
@@ -17,12 +15,18 @@ fig = plt.figure(
     columns=10,  # Either rows or columns could be omitted
     values=[30, 16, 4]
 )
-fig.show()
+fig.savefig("plot.png", bbox_inches="tight")
 ```
 
 <img class="img_middle" alt="With list values" src="https://raw.githubusercontent.com/gyli/PyWaffle/master/examples/docs/basic_list_values.svg?sanitize=true">
 
-Parameter `values` also accepts data in dict. The key of the dict would be used as labels and shown in legends.
+> **_NOTE:_** One of the parameter `rows` and `columns` is redundant in this case, since both of the chart size and value sum are 50. So, either one of `rows` and `columns` could be omitted, and it can still be calculated through value sum automatically. See [Auto-sizing](value_scaling_and_auto_sizing.md) for more details. 
+
+---
+
+### Values in Dictionary
+
+Parameter `values` also accepts data in a dictionary. The dictionary key will be used as labels and shown in legends.
 
 ```python
 plt.figure(
@@ -35,3 +39,28 @@ plt.figure(
 ```
 
 <img class="img_middle" alt="With dict values" src="https://raw.githubusercontent.com/gyli/PyWaffle/master/examples/docs/basic_dict_values.svg?sanitize=true">
+
+---
+
+### Values in pandas.DataFrame
+
+Other than list and dictionary, Parameter `values` also accepts a column of pandas `DataFrame`.
+
+However, unlike values in a dictionary that can generate labels and legend automatically, `Waffle` does not use `DataFrame` as label by default. So you have to pass the index to parameter `labels` manually, if you would like to use column index as label.
+
+```python
+import pandas as pd
+
+data = [30, 16, 4]
+df = pd.DataFrame(data, columns=['Value'], index=['Cat1', 'Cat2', 'Cat3'])
+
+
+plt.figure(
+    FigureClass=Waffle,
+    rows=5,
+    columns=10,
+    values=df['Value'],
+    labels=list(df.index),  # Legend would not be created without this line
+    legend={'loc': 'upper left', 'bbox_to_anchor': (1, 1)}
+)
+```

docs/examples/plot_with_characters_or_icons.md

@@ -25,9 +25,13 @@ To specify the font, pass the absolute path to a .ttf or .otf file to parameter
 
 ## Icons
 
-### Icon Size
+Waffle Chart with icons is also known as Pictogram Chart. 
+
+PyWaffle supports plotting with icons through [Font Awesome](https://fontawesome.com/). See page [Font Awesome Integration](font_awesome_integration.html) for how Font Awesome is integrated into PyWaffle.
 
-Waffle Chart with icons is also known as Pictogram Chart. PyWaffle supports plotting with [Font Awesome icons](https://fontawesome.com/).
+For searching available icon name in Font Awesome, please visit [https://fontawesome.com/search](https://fontawesome.com/search).
+
+### Icon Size
 
 When using icons, the parameters for setting block size would be ignored, including `interval_ratio_x`, `interval_ratio_y` and `block_aspect_ratio`. Instead, use `font_size` to set the size of icons. For allowed sizes, see [FontProperties.set_size](https://matplotlib.org/stable/api/font_manager_api.html#matplotlib.font_manager.FontProperties.set_size).