We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
[DOC] Adding minimal working examples to docstrings; a checklist
## Background

This thread is borne out of the discussion from #968 , in an effort to make documentation more beginner-friendly & more understandable.
One of the subtasks mentioned in that thread was to go through the function docstrings and include a *minimal* working example to each of the public functions in pyjanitor.

Criteria reiterated here for the benefit of discussion:

>     It should fit with our existing choice to go with mkdocs, mkdocstrings, and mknotebooks.
>     The examples should be minimal and executable and complete execution within 5 seconds per function.
>     The examples should display in rich HTML on our docs page.
>     We should have an automatic way of identifying whether a function has an example provided or not so that every function has an example.

Sample of what MWE should look like is shown [here](https://github.com/pyjanitor-devs/pyjanitor/issues/968#issuecomment-1003672331).

---

I'm thinking we can create a task list so that 1. we can encourage more users to join in the effort, and 2. make sure we don't do duplicate work. A lot of the groundwork can be covered by selectively copying one or two examples over from the software test suite.

Then we can label this issue as a Help Wanted / Low-Hanging Fruit and get people to mention in this thread if they're intending to work on the files?

### Task list

- [X] functions/add_columns.py
- [x] functions/also.py
- [x] functions/bin_numeric.py
- [x] functions/case_when.py
- [x] functions/change_type.py
- [x] functions/clean_names.py
- [x] functions/coalesce.py
- [x] functions/collapse_levels.py
- [x] functions/complete.py
- [x] functions/concatenate_columns.py
- [x] functions/conditional_join.py
- [x] functions/convert_date.py
- [x] functions/count_cumulative_unique.py
- [x] functions/currency_column_to_numeric.py
- [x] functions/deconcatenate_column.py
- [x] functions/drop_constant_columns.py
- [x] functions/drop_duplicate_columns.py
- [x] functions/dropnotnull.py
- [x] functions/encode_categorical.py
- [x] functions/expand_column.py
- [x] functions/expand_grid.py
- [x] functions/factorize_columns.py
- [x] functions/fill.py
- [x] functions/filter.py
- [x] functions/find_replace.py
- [x] functions/flag_nulls.py
- [x] functions/get_dupes.py
- [x] functions/groupby_agg.py
- [x] functions/groupby_topk.py
- [x] functions/impute.py
- [x] functions/jitter.py
- [x] functions/join_apply.py
- [x] functions/label_encode.py
- [x] functions/limit_column_characters.py
- [x] functions/min_max_scale.py
- [x] functions/move.py
- [x] functions/pivot.py
- [x] functions/process_text.py
- [x] functions/remove_columns.py
- [x] functions/remove_empty.py
- [x] functions/rename_columns.py
- [x] functions/reorder_columns.py
- [x] functions/round_to_fraction.py
- [x] functions/row_to_names.py
- [x] functions/select_columns.py
- [x] functions/shuffle.py
- [x] functions/sort_column_value_order.py
- [x] functions/sort_naturally.py
- [x] functions/take_first.py
- [x] functions/then.py
- [x] functions/to_datetime.py
- [x] functions/toset.py
- [x] functions/transform_columns.py
- [x] functions/truncate_datetime.py
- [x] functions/update_where.py
- [ ] spark/backend.py
- [ ] spark/functions.py
- [x] xarray/functions.py
- [x] biology.py
- [x] chemistry.py
- [x] engineering.py
- [ ] errors.py
- [x] finance.py
- [x] io.py
- [x] math.py
- [x] ml.py
- [x] timeseries.py
B

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `janitor/functions/update_where.py`
Content:
```
1 from typing import Any, Hashable
2 import pandas_flavor as pf
3 import pandas as pd
4 from janitor.utils import deprecated_alias
5 from pandas.api.types import is_bool_dtype
6 
7 
8 @pf.register_dataframe_method
9 @deprecated_alias(target_col="target_column_name")
10 def update_where(
11     df: pd.DataFrame,
12     conditions: Any,
13     target_column_name: Hashable,
14     target_val: Any,
15 ) -> pd.DataFrame:
16     """
17     Add multiple conditions to update a column in the dataframe.
18 
19     This method does not mutate the original DataFrame.
20 
21     Example usage:
22 
23     ```python
24         data = {
25             "a": [1, 2, 3, 4],
26             "b": [5, 6, 7, 8],
27             "c": [0, 0, 0, 0]
28         }
29         df = pd.DataFrame(data)
30 
31            a  b  c
32         0  1  5  0
33         1  2  6  0
34         2  3  7  0
35         3  4  8  0
36 
37         df.update_where(conditions = (df.a > 2) & (df.b < 8),
38                         target_column_name = 'c',
39                         target_val = 10)
40 
41            a  b   c
42         0  1  5   0
43         1  2  6   0
44         2  3  7  10
45         3  4  8   0
46     ```
47 
48     `update_where` also supports pandas *query* style string expressions:
49 
50     ```python
51         df.update_where(conditions = "a > 2 and b < 8",
52                         target_column_name = 'c',
53                         target_val = 10)
54 
55            a  b   c
56         0  1  5   0
57         1  2  6   0
58         2  3  7  10
59         3  4  8   0
60     ```
61 
62 
63     :param df: The pandas DataFrame object.
64     :param conditions: Conditions used to update a target column
65         and target value.
66     :param target_column_name: Column to be updated. If column does not exist
67         in DataFrame, a new column will be created; note that entries that do
68         not get set in the new column will be null.
69     :param target_val: Value to be updated
70     :returns: A pandas DataFrame.
71     :raises ValueError: if `conditions` does not return a boolean array-like
72         data structure.
73 
74     .. # noqa: DAR402
75     """
76 
77     df = df.copy()
78 
79     # use query mode if a string expression is passed
80     if isinstance(conditions, str):
81         conditions = df.eval(conditions)
82 
83     if not is_bool_dtype(conditions):
84         raise ValueError(
85             """
86             Kindly ensure that `conditions` passed
87             evaluates to a Boolean dtype.
88             """
89         )
90 
91     df.loc[conditions, target_column_name] = target_val
92 
93     return df
94
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/janitor/functions/update_where.py b/janitor/functions/update_where.py
--- a/janitor/functions/update_where.py
+++ b/janitor/functions/update_where.py
@@ -1,3 +1,7 @@
+"""
+Function for updating values based on other column values
+"""
+
 from typing import Any, Hashable
 import pandas_flavor as pf
 import pandas as pd
@@ -20,45 +24,38 @@
 
     Example usage:
 
-    ```python
-        data = {
-            "a": [1, 2, 3, 4],
-            "b": [5, 6, 7, 8],
-            "c": [0, 0, 0, 0]
-        }
-        df = pd.DataFrame(data)
-
-           a  b  c
-        0  1  5  0
-        1  2  6  0
-        2  3  7  0
-        3  4  8  0
-
-        df.update_where(conditions = (df.a > 2) & (df.b < 8),
-                        target_column_name = 'c',
-                        target_val = 10)
-
-           a  b   c
-        0  1  5   0
-        1  2  6   0
-        2  3  7  10
-        3  4  8   0
-    ```
-
-    `update_where` also supports pandas *query* style string expressions:
-
-    ```python
-        df.update_where(conditions = "a > 2 and b < 8",
-                        target_column_name = 'c',
-                        target_val = 10)
-
-           a  b   c
-        0  1  5   0
-        1  2  6   0
-        2  3  7  10
-        3  4  8   0
-    ```
-
+    >>> data = {
+    ...    "a": [1, 2, 3, 4],
+    ...    "b": [5, 6, 7, 8],
+    ...    "c": [0, 0, 0, 0],
+    ... }
+    >>> df = pd.DataFrame(data)
+    >>> df
+       a  b  c
+    0  1  5  0
+    1  2  6  0
+    2  3  7  0
+    3  4  8  0
+    >>> df.update_where(
+    ...    conditions = (df.a > 2) & (df.b < 8),
+    ...    target_column_name = 'c',
+    ...    target_val = 10
+    ... )
+       a  b   c
+    0  1  5   0
+    1  2  6   0
+    2  3  7  10
+    3  4  8   0
+    >>> df.update_where( # supports pandas *query* style string expressions
+    ...    conditions = "a > 2 and b < 8",
+    ...    target_column_name = 'c',
+    ...    target_val = 10
+    ... )
+       a  b   c
+    0  1  5   0
+    1  2  6   0
+    2  3  7  10
+    3  4  8   0
 
     :param df: The pandas DataFrame object.
     :param conditions: Conditions used to update a target column

{"golden_diff": "diff --git a/janitor/functions/update_where.py b/janitor/functions/update_where.py\n--- a/janitor/functions/update_where.py\n+++ b/janitor/functions/update_where.py\n@@ -1,3 +1,7 @@\n+\"\"\"\n+Function for updating values based on other column values\n+\"\"\"\n+\n from typing import Any, Hashable\n import pandas_flavor as pf\n import pandas as pd\n@@ -20,45 +24,38 @@\n \n     Example usage:\n \n-    ```python\n-        data = {\n-            \"a\": [1, 2, 3, 4],\n-            \"b\": [5, 6, 7, 8],\n-            \"c\": [0, 0, 0, 0]\n-        }\n-        df = pd.DataFrame(data)\n-\n-           a  b  c\n-        0  1  5  0\n-        1  2  6  0\n-        2  3  7  0\n-        3  4  8  0\n-\n-        df.update_where(conditions = (df.a > 2) & (df.b < 8),\n-                        target_column_name = 'c',\n-                        target_val = 10)\n-\n-           a  b   c\n-        0  1  5   0\n-        1  2  6   0\n-        2  3  7  10\n-        3  4  8   0\n-    ```\n-\n-    `update_where` also supports pandas *query* style string expressions:\n-\n-    ```python\n-        df.update_where(conditions = \"a > 2 and b < 8\",\n-                        target_column_name = 'c',\n-                        target_val = 10)\n-\n-           a  b   c\n-        0  1  5   0\n-        1  2  6   0\n-        2  3  7  10\n-        3  4  8   0\n-    ```\n-\n+    >>> data = {\n+    ...    \"a\": [1, 2, 3, 4],\n+    ...    \"b\": [5, 6, 7, 8],\n+    ...    \"c\": [0, 0, 0, 0],\n+    ... }\n+    >>> df = pd.DataFrame(data)\n+    >>> df\n+       a  b  c\n+    0  1  5  0\n+    1  2  6  0\n+    2  3  7  0\n+    3  4  8  0\n+    >>> df.update_where(\n+    ...    conditions = (df.a > 2) & (df.b < 8),\n+    ...    target_column_name = 'c',\n+    ...    target_val = 10\n+    ... )\n+       a  b   c\n+    0  1  5   0\n+    1  2  6   0\n+    2  3  7  10\n+    3  4  8   0\n+    >>> df.update_where( # supports pandas *query* style string expressions\n+    ...    conditions = \"a > 2 and b < 8\",\n+    ...    target_column_name = 'c',\n+    ...    target_val = 10\n+    ... )\n+       a  b   c\n+    0  1  5   0\n+    1  2  6   0\n+    2  3  7  10\n+    3  4  8   0\n \n     :param df: The pandas DataFrame object.\n     :param conditions: Conditions used to update a target column\n", "issue": "[DOC] Adding minimal working examples to docstrings; a checklist\n## Background\r\n\r\nThis thread is borne out of the discussion from #968 , in an effort to make documentation more beginner-friendly & more understandable.\r\nOne of the subtasks mentioned in that thread was to go through the function docstrings and include a *minimal* working example to each of the public functions in pyjanitor.\r\n\r\nCriteria reiterated here for the benefit of discussion:\r\n\r\n>     It should fit with our existing choice to go with mkdocs, mkdocstrings, and mknotebooks.\r\n>     The examples should be minimal and executable and complete execution within 5 seconds per function.\r\n>     The examples should display in rich HTML on our docs page.\r\n>     We should have an automatic way of identifying whether a function has an example provided or not so that every function has an example.\r\n\r\nSample of what MWE should look like is shown [here](https://github.com/pyjanitor-devs/pyjanitor/issues/968#issuecomment-1003672331).\r\n\r\n---\r\n\r\nI'm thinking we can create a task list so that 1. we can encourage more users to join in the effort, and 2. make sure we don't do duplicate work. A lot of the groundwork can be covered by selectively copying one or two examples over from the software test suite.\r\n\r\nThen we can label this issue as a Help Wanted / Low-Hanging Fruit and get people to mention in this thread if they're intending to work on the files?\r\n\r\n### Task list\r\n\r\n- [X] functions/add_columns.py\r\n- [x] functions/also.py\r\n- [x] functions/bin_numeric.py\r\n- [x] functions/case_when.py\r\n- [x] functions/change_type.py\r\n- [x] functions/clean_names.py\r\n- [x] functions/coalesce.py\r\n- [x] functions/collapse_levels.py\r\n- [x] functions/complete.py\r\n- [x] functions/concatenate_columns.py\r\n- [x] functions/conditional_join.py\r\n- [x] functions/convert_date.py\r\n- [x] functions/count_cumulative_unique.py\r\n- [x] functions/currency_column_to_numeric.py\r\n- [x] functions/deconcatenate_column.py\r\n- [x] functions/drop_constant_columns.py\r\n- [x] functions/drop_duplicate_columns.py\r\n- [x] functions/dropnotnull.py\r\n- [x] functions/encode_categorical.py\r\n- [x] functions/expand_column.py\r\n- [x] functions/expand_grid.py\r\n- [x] functions/factorize_columns.py\r\n- [x] functions/fill.py\r\n- [x] functions/filter.py\r\n- [x] functions/find_replace.py\r\n- [x] functions/flag_nulls.py\r\n- [x] functions/get_dupes.py\r\n- [x] functions/groupby_agg.py\r\n- [x] functions/groupby_topk.py\r\n- [x] functions/impute.py\r\n- [x] functions/jitter.py\r\n- [x] functions/join_apply.py\r\n- [x] functions/label_encode.py\r\n- [x] functions/limit_column_characters.py\r\n- [x] functions/min_max_scale.py\r\n- [x] functions/move.py\r\n- [x] functions/pivot.py\r\n- [x] functions/process_text.py\r\n- [x] functions/remove_columns.py\r\n- [x] functions/remove_empty.py\r\n- [x] functions/rename_columns.py\r\n- [x] functions/reorder_columns.py\r\n- [x] functions/round_to_fraction.py\r\n- [x] functions/row_to_names.py\r\n- [x] functions/select_columns.py\r\n- [x] functions/shuffle.py\r\n- [x] functions/sort_column_value_order.py\r\n- [x] functions/sort_naturally.py\r\n- [x] functions/take_first.py\r\n- [x] functions/then.py\r\n- [x] functions/to_datetime.py\r\n- [x] functions/toset.py\r\n- [x] functions/transform_columns.py\r\n- [x] functions/truncate_datetime.py\r\n- [x] functions/update_where.py\r\n- [ ] spark/backend.py\r\n- [ ] spark/functions.py\r\n- [x] xarray/functions.py\r\n- [x] biology.py\r\n- [x] chemistry.py\r\n- [x] engineering.py\r\n- [ ] errors.py\r\n- [x] finance.py\r\n- [x] io.py\r\n- [x] math.py\r\n- [x] ml.py\r\n- [x] timeseries.py\r\nB\n", "before_files": [{"content": "from typing import Any, Hashable\nimport pandas_flavor as pf\nimport pandas as pd\nfrom janitor.utils import deprecated_alias\nfrom pandas.api.types import is_bool_dtype\n\n\n@pf.register_dataframe_method\n@deprecated_alias(target_col=\"target_column_name\")\ndef update_where(\n    df: pd.DataFrame,\n    conditions: Any,\n    target_column_name: Hashable,\n    target_val: Any,\n) -> pd.DataFrame:\n    \"\"\"\n    Add multiple conditions to update a column in the dataframe.\n\n    This method does not mutate the original DataFrame.\n\n    Example usage:\n\n    ```python\n        data = {\n            \"a\": [1, 2, 3, 4],\n            \"b\": [5, 6, 7, 8],\n            \"c\": [0, 0, 0, 0]\n        }\n        df = pd.DataFrame(data)\n\n           a  b  c\n        0  1  5  0\n        1  2  6  0\n        2  3  7  0\n        3  4  8  0\n\n        df.update_where(conditions = (df.a > 2) & (df.b < 8),\n                        target_column_name = 'c',\n                        target_val = 10)\n\n           a  b   c\n        0  1  5   0\n        1  2  6   0\n        2  3  7  10\n        3  4  8   0\n    ```\n\n    `update_where` also supports pandas *query* style string expressions:\n\n    ```python\n        df.update_where(conditions = \"a > 2 and b < 8\",\n                        target_column_name = 'c',\n                        target_val = 10)\n\n           a  b   c\n        0  1  5   0\n        1  2  6   0\n        2  3  7  10\n        3  4  8   0\n    ```\n\n\n    :param df: The pandas DataFrame object.\n    :param conditions: Conditions used to update a target column\n        and target value.\n    :param target_column_name: Column to be updated. If column does not exist\n        in DataFrame, a new column will be created; note that entries that do\n        not get set in the new column will be null.\n    :param target_val: Value to be updated\n    :returns: A pandas DataFrame.\n    :raises ValueError: if `conditions` does not return a boolean array-like\n        data structure.\n\n    .. # noqa: DAR402\n    \"\"\"\n\n    df = df.copy()\n\n    # use query mode if a string expression is passed\n    if isinstance(conditions, str):\n        conditions = df.eval(conditions)\n\n    if not is_bool_dtype(conditions):\n        raise ValueError(\n            \"\"\"\n            Kindly ensure that `conditions` passed\n            evaluates to a Boolean dtype.\n            \"\"\"\n        )\n\n    df.loc[conditions, target_column_name] = target_val\n\n    return df\n", "path": "janitor/functions/update_where.py"}], "after_files": [{"content": "\"\"\"\nFunction for updating values based on other column values\n\"\"\"\n\nfrom typing import Any, Hashable\nimport pandas_flavor as pf\nimport pandas as pd\nfrom janitor.utils import deprecated_alias\nfrom pandas.api.types import is_bool_dtype\n\n\n@pf.register_dataframe_method\n@deprecated_alias(target_col=\"target_column_name\")\ndef update_where(\n    df: pd.DataFrame,\n    conditions: Any,\n    target_column_name: Hashable,\n    target_val: Any,\n) -> pd.DataFrame:\n    \"\"\"\n    Add multiple conditions to update a column in the dataframe.\n\n    This method does not mutate the original DataFrame.\n\n    Example usage:\n\n    >>> data = {\n    ...    \"a\": [1, 2, 3, 4],\n    ...    \"b\": [5, 6, 7, 8],\n    ...    \"c\": [0, 0, 0, 0],\n    ... }\n    >>> df = pd.DataFrame(data)\n    >>> df\n       a  b  c\n    0  1  5  0\n    1  2  6  0\n    2  3  7  0\n    3  4  8  0\n    >>> df.update_where(\n    ...    conditions = (df.a > 2) & (df.b < 8),\n    ...    target_column_name = 'c',\n    ...    target_val = 10\n    ... )\n       a  b   c\n    0  1  5   0\n    1  2  6   0\n    2  3  7  10\n    3  4  8   0\n    >>> df.update_where( # supports pandas *query* style string expressions\n    ...    conditions = \"a > 2 and b < 8\",\n    ...    target_column_name = 'c',\n    ...    target_val = 10\n    ... )\n       a  b   c\n    0  1  5   0\n    1  2  6   0\n    2  3  7  10\n    3  4  8   0\n\n    :param df: The pandas DataFrame object.\n    :param conditions: Conditions used to update a target column\n        and target value.\n    :param target_column_name: Column to be updated. If column does not exist\n        in DataFrame, a new column will be created; note that entries that do\n        not get set in the new column will be null.\n    :param target_val: Value to be updated\n    :returns: A pandas DataFrame.\n    :raises ValueError: if `conditions` does not return a boolean array-like\n        data structure.\n\n    .. # noqa: DAR402\n    \"\"\"\n\n    df = df.copy()\n\n    # use query mode if a string expression is passed\n    if isinstance(conditions, str):\n        conditions = df.eval(conditions)\n\n    if not is_bool_dtype(conditions):\n        raise ValueError(\n            \"\"\"\n            Kindly ensure that `conditions` passed\n            evaluates to a Boolean dtype.\n            \"\"\"\n        )\n\n    df.loc[conditions, target_column_name] = target_val\n\n    return df\n", "path": "janitor/functions/update_where.py"}]}