[DOC] Adding minimal working examples to docstrings; a checklist

[thatlittleboy]

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.

---

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

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

[thatlittleboy]

• 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

[ericmjl]

This is awesome, @thatlittleboy! Thank you for handling this here 😄. I've invited you to the dev team to help move this along.

[ericmjl]

One trick I'm finding is that it's pretty easy to create a minimal working example from the test suite 😹.

[thatlittleboy]

Ongoing sprint, dibs on the following:

• functions/change_type.py
• functions/coalesce.py
• functions/collapse_levels.py
• functions/filter.py

[ericmjl]

Same here, dibs on:

• functions/take_first.py
• functions/sort_naturally.py

[ericmjl]

Dibs on:

• functions/min_max_scale.py
• functions/move.py

Two per PR seems to be the load that I personally can handle 😹.

[thatlittleboy]

Ongoing sprint:

• functions/concatenate_columns.py
• functions/deconcatenate_column.py
• functions/select_columns.py

[ericmjl]

Going to work on:

• functions/drop_constant_columns.py
• functions/drop_duplicate_columns.py

[thatlittleboy]

Ongoing sprint:

• functions/move.py
• functions/remove_columns.py
• functions/remove_empty.py
• functions/limit_column_characters.py

[thatlittleboy]

Ongoing sprint:

• functions/round_to_fraction.py
• functions/row_to_names.py
• functions/shuffle.py

[thatlittleboy]

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

[SamBauter]

Pycon 2022 - working on timeseries.py

[gahjelle]

I'll also do functions/find_replace.py

[Econundrums]

I'll do functions/fill.py

[ethompsy]

Pycon 2022 - working on functions/get_dupes.py

[ethompsy]

Pycon 2022 - working on functions/groupby_topk.py

[gahjelle]

I'll do math.py

[Econundrums]

Dibs on functions/transform_columns.py

[catherinedevlin]

For my next trick, I'd like to do biology.py

[Econundrums]

It looks like transform_columns.py is already done :(

Dibs on update_where.py

[dancassin]

Dibs on finance.py

[gahjelle]

I'll do ml.py next

[gahjelle]

I'll do xarray/functions.py

[Zeroto521]

functions/min_max_scale.py done via #1107 and #1112