bqplot · ChakriCherukuri · Feb 3, 2023 · Feb 3, 2023 · Feb 3, 2023 · Feb 3, 2023
diff --git a/docs/assets/images/bars-image1.png b/docs/assets/images/bars-image1.png
diff --git a/docs/assets/images/bars-image2.png b/docs/assets/images/bars-image2.png
diff --git a/docs/assets/images/bars-image3.png b/docs/assets/images/bars-image3.png
diff --git a/docs/assets/images/bars-image4.png b/docs/assets/images/bars-image4.png
diff --git a/docs/assets/images/bars-image5.png b/docs/assets/images/bars-image5.png
diff --git a/docs/index.md b/docs/index.md
@@ -36,7 +36,7 @@ Two APIs are provided in bqplot:
 
 * [__Object Model__](usage/object-model.md)
     * Based on the constructs of Grammar of Graphics
-    * Users need to explicitly create `Figure`, `Mark`, `Axis` and `Scale` objects
+    * Users need to explicitly create [`Scale`](api/scales.md), [`Mark`](api/marks.md), [`Axis`](api/axes.md) and [`Figure`](api/figure.md) objects
     * Verbose API
     * Fully customizable
     * Extensible

diff --git a/docs/usage/marks/bars.md b/docs/usage/marks/bars.md
@@ -1 +1,142 @@
-# This docs does not exist yet!
+The `Bars` mark provides the following features:
+
+* Plot a single or multiple arrays of y-values for a single array of __categorical__ x-values
+* Support for horizontal bar charts
+* Support for stacked and grouped bar charts
+
+### Attributes
+
+#### [Data Attributes](../../api/marks.md#bqplot.marks.Bars--data-attributes)
+
+#### [Style Attributes](../../api/marks.md#bqplot.marks.Bars--style-attributes)
+
+
+Let's now look at examples of constructing bar charts using the `pyplot` API
+
+### pyplot
+The function for plotting bar charts in `pyplot` is [`plt.bar`](../../api/pyplot.md#bqplot.pyplot.bar). It takes two main arguments:
+
+1. __x__ vector of x values
+2. __y__ vector of y values (_For stacked/grouped bar charts `y` should be a list of arrays or a 2-d array_)
+
+For further customization, any of the attributes above can be passed as keyword args.
+
+### Code Examples
+#### Simple Bar Chart
+```py hl_lines="9"
+import bqplot.pyplot as plt
+import numpy as np
+
+fig = plt.figure(title="Bar Chart")
+
+x = list("ABCDE")
+y = np.random.rand(5)
+
+bar = plt.bar(x, y)
+
+fig
+```
+![plot](../../assets/images/bars-image1.png)
+!!! tip
+    To render bar charts professionally it's better to disable `x` grid lines. Also set the opacity to be slightly less than 1 to make the bars a bit transparent, like so:
+    ```py
+    axes_options = {"x": {"grid_lines": "none"}}
+    bar = plt.bar(x, y, axes_options=axes_options, opacities=[.9])
+    ```
+
+
+Attributes can be updated in separate notebook cells or in callbacks when an event is triggered!
+```py
+# update the line color and opacity
+bar.colors = ["red"]
+bar.opacities = [.5]
+```
+#### Bar Spacing
+Use the `padding` attribute (between 0 and 1) to increase or decrease the spacing between bars. 
+`padding` values close to 0 means almost no padding between bars, thereby making the bars fat!
+
+=== "During Construction"
+    ```py
+    bar = plt.bar(x, y, padding=0.3)
+    ```
+
+=== "Update After Construction"
+    ```py
+    bar.padding = 0.3
+    ```
+
+#### Horizontal Bar Chart
+Use [`pyplot.barh`](../../api/pyplot.md#bqplot.pyplot.barh) method to create a horizontal bar chart, like so:
+
+```py hl_lines="7"
+fig = plt.figure(title="Horizontal Bar Chart")
+
+x = list("ABCDE")
+y = np.random.rand(5)
+
+axes_options = {"x": {"grid_lines": "none"}}
+bar = plt.barh(x, y, colors=["salmon"], axes_options=axes_options, opacities=[.9])
+
+fig
+```
+![plot](../../assets/images/bars-image2.png)
+
+#### Stacked/Grouped Bar Charts
+Use the `type` attribute for stacked/grouped bar charts, like so:
+
+=== "Stacked"
+
+    ```py hl_lines="5"
+    fig = plt.figure(title="Stacked Bar Chart")
+    x = list("ABCDE")
+    y = np.random.rand(3, 5) # 2d array
+
+    stacked_bar = plt.bar(x, y, type="stacked", padding=.4,
+                          colors=["orangered", "steelblue", "limegreen"])
+
+    fig
+    ```
+    ![plot](../../assets/images/bars-image3.png)
+
+=== "Grouped"
+
+    ```py hl_lines="5"
+    fig = plt.figure(title="Stacked Bar Chart")
+    x = list("ABCDE")
+    y = np.random.rand(3, 5) # 2d array
+
+    grouped_bar = plt.bar(x, y, type="grouped", padding=.4,
+                          colors=["orangered", "steelblue", "limegreen"])
+
+    fig
+    ```
+    ![plot](../../assets/images/bars-image4.png)
+
+
+#### Using `color` data attribute
+Using `color` __data__ attribute we can encode a third dimension (apart from `x` and `y`) using color scales, like so:
+
+```py hl_lines="3 4 10 12"
+import bqplot as bq
+
+# provide enough bottom margin to accommodate the color bar
+fig = plt.figure(fig_margin = dict(top=50, bottom=80, left=50, right=50))
+
+x = list("ABCDE")
+y, color = np.random.rand(2, 5) 
+
+# add a 'reds' scheme color scale
+plt.scales(scales={"color": bq.ColorScale(scheme="Reds", min=0, max=1)})
+
+bar = plt.bar(x, y, color=color, padding=0.2)
+
+fig
+```
+![plot](../../assets/images/bars-image5.png)
+
+
+### Example Notebooks
+For detailed examples of plotting bar charts, refer to the following example notebooks:
+
+1. [pyplot](https://github.com/bqplot/bqplot/blob/master/examples/Marks/Pyplot/Bars.ipynb)
+2. [Object Model](https://github.com/bqplot/bqplot/blob/master/examples/Marks/Object%20Model/Bars.ipynb)
diff --git a/docs/usage/marks/lines.md b/docs/usage/marks/lines.md
@@ -90,7 +90,7 @@ plt.scales(scales={"x": bq.DateScale()})
 time_series_line = plt.plot(x, y, "r", stroke_width=1,
                             fill="bottom", # (1)!
                             fill_colors=["red"],
-                            fill_opacities=[.4]))
+                            fill_opacities=[.4])
 fig
 ```
 

diff --git a/docs/usage/object-model.md b/docs/usage/object-model.md
@@ -1,6 +1,6 @@
 `bqplot` is based on _Grammar of Graphics_ paradigm. The Object Model provides the user an object-oriented interface for building plots. This means the API is verbose but fully customizable.
 
-Following are the core components in the `Object Model`:
+Following are the core components of the `Object Model`:
 
 1. [Scales](../api/scales.md)
 2. [Marks](../api/marks.md)
@@ -16,7 +16,7 @@ The following are the steps to build a Figure in bqplot using the Object Model:
 4. Finally create a figure using `Figure` class. Figure takes marks and axes as inputs.
 __Figure object is a instance of `DOMWidget` and can be rendered like any other jupyter widgets__
 
-Let's look a few examples (`pyplot` usage available [here](pyplot.md)):
+Let's look a few examples (`pyplot` usage available [here](pyplot.md#line-chart)):
 
 #### Line Chart
 ```py

diff --git a/docs/usage/pyplot.md b/docs/usage/pyplot.md
@@ -1,6 +1,4 @@
-`pyplot` is a context based functional API offering meaningful defaults. It's a concise API and very similar to matplotlib's pyplot. __Users new to bqplot should use `pyplot` as a starting point__. 
-
-`pyplot` API documentation can be found [here](../api/pyplot.md).
+[`pyplot`](../api/pyplot.md) is a context based functional API offering meaningful defaults. It's a concise API and very similar to matplotlib's pyplot. __Users new to bqplot should use `pyplot` as a starting point__.
 
 Steps for building plots in `pyplot`:
 
@@ -23,7 +21,7 @@ Steps for building plots in `pyplot`:
 * `plt.hline`: draws a horizontal line at a specified level
 * `plt.vline`: draws a vertical line at a specified level
 
-Let's look at a few examples (`Object Model` usage available [here](object-model.md)):
+Let's look at a few examples (`Object Model` usage available [here](object-model.md#line-chart)):
 
 #### Line Chart
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -33,13 +33,14 @@ theme:
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.inlinehilite
   - admonition
   - pymdownx.details
   - pymdownx.superfences
   - md_in_html
   - attr_list
-
 plugins:
   - search
   - mkdocstrings: