Repository: pyjanitor-devs/pyjanitor

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


Discussion:
- `functions/bin_numeric.py` is already in PR

I'm currently having a look at
- `functions/rename_columns.py`
- `functions/reorder_columns.py`
- `functions/to_datetime.py`
- `functions/also.py`
- `functions/then.py`
- `functions/dropnotnull.py`
- `functions/groupby_agg.py`
- `functions/flag_nulls.py`

Will probably look at some more as and when I have time over the next week or so
This is awesome, @thatlittleboy! Thank you for handling this here :smile:. I've invited you to the dev team to help move this along. 
One trick I'm finding is that it's pretty easy to create a minimal working example from the test suite :joy_cat:.
Ongoing sprint, dibs on the following:
* `functions/change_type.py`
* `functions/coalesce.py`
* `functions/collapse_levels.py`
* `functions/filter.py`


Same here, dibs on:

* `functions/take_first.py`
* `functions/sort_naturally.py`
Dibs on:

- functions/min_max_scale.py
- functions/move.py

Two per PR seems to be the load that I personally can handle :joy_cat:.
Ongoing sprint:
* `functions/concatenate_columns.py`
* `functions/deconcatenate_column.py`
* `functions/select_columns.py`
Going to work on:

- `functions/drop_constant_columns.py`
- `functions/drop_duplicate_columns.py`

Ongoing sprint:
- `functions/move.py`
- `functions/remove_columns.py`
- `functions/remove_empty.py`
- `functions/limit_column_characters.py`
Ongoing sprint:
- `functions/round_to_fraction.py`
- `functions/row_to_names.py`
- `functions/shuffle.py`
Currently looking at:

- functions/impute.py
- functions/jitter.py
- functions/join_apply.py

Also in the midst of updating:
- functions/encode_categorical.py
- functions/label_encode.py
- functions/factorize_columns.py

hi - this is amie from pycon 2022 sprints, i am claiming:
 functions/convert_date.py
Hey, I'm Geir Arne @ the PyCon US 2022 sprints.

I'm claiming `functions/expand_column.py` to work on.
It's Catherine Devlin at PyCon 2022!

I'll start on chemistry.py.
Pycon 2022 - working on timeseries.py
I'll also do `functions/find_replace.py`
I'll do functions/fill.py
Pycon 2022 - working on `functions/get_dupes.py`
Pycon 2022 - working on `functions/groupby_topk.py`
I'll do `math.py`

Resolving patch:
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 @@ def update_where(
 
     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


Test patch: