[DOC] Improve the examples in janitor.functions.py

[dave-frazzetto]

Some docs in the functions in the janitor.functions.py file present runnable code examples, others don't. It could be made consistent through all functions (unless trivial)

[ericmjl]

Indeed! I'd be happy to accept individual PRs per example, with new issues are raised per example to keep track of progress.

[SorenFrohlich]

I have started changing the doc-strings of some of the more advanced functions in functions.py

[ericmjl]

Thanks @SorenFrohlich! Looking forward to your PRs :smile:.

[samukweku]

Hi Team, great work with the pyjanitor package. I noticed that some functions do not have examples attached to them. Examples would make the functions, in my opinion, much clearer. I would love to take this up, if no one is currently working on it, as it is my first time making a contribution to open source.

[ericmjl]

@samukweku we would love to see a contribution from you! Examples are usually the hardest for maintainers to write, so I’d love to see what you’ve got!

Going forward, let’s build it up one by one. We can use this issue to track progress. Which do you think would be the easiest for you to get started? Let’s take it from there!

[samukweku]

Cool. I will start off with groupby_agg and create an example. By the way, for the groupby_agg function, one of the parameters listed is axis, which when used returns this error: 'TypeError: groupby_agg() got an unexpected keyword argument 'axis'. Wondering if that argument should be there in the first place.

[samukweku]

Hi @ericmjl and the rest of the team. I have created an example for one of the functions and want to make a pull request. However, I need your advice on an error I am getting:

Any idea what make: *** [Makefile:23: test] Killed means? make: *** [Makefile:20: html] Error 137 ? How do I fix the errors?

(pyjanitor-dev) sam@pop-os:~/github_cloned_projects/pyjanitor$ make check Running test suite... pytest --cov-report html ##vso[task.logissue type=warning;]The 'junit_family' default value will change to 'xunit2' in pytest 6.0. Add 'junit_family=xunit1' to your pytest.ini file to keep the current format in future versions of pytest and silence this warning. ============================= test session starts ============================== platform linux -- Python 3.7.6, pytest-5.3.4, py-1.8.1, pluggy-0.13.1 rootdir: /home/sam/github_cloned_projects/pyjanitor, inifile: pytest.ini plugins: azurepipelines-0.8.0, hypothesis-5.2.0, cov-2.8.1 collecting 21 items make: *** [Makefile:23: test] Killed

I decided to run each line and got the same error for pytest. I also got an error for 'cd docs && make html': make: *** [Makefile:20: html] Error 137

The complete output is here:

(pyjanitor-dev) sam@pop-os:~/github_cloned_projects/pyjanitor$ cd docs && make html Running Sphinx v2.3.1 Making symlink to ../examples/notebooks notebooks directory already exists. Not creating.. loading intersphinx inventory from https://docs.python.org/objects.inv... loading intersphinx inventory from https://pandas.pydata.org/pandas-docs/stable/objects.inv... intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv [autosummary] generating autosummary for: CONTRIBUTION_TYPES.rst, PYCHARM_USERS.rst, authors.rst, contributing.rst, index.rst, installation.rst, janitor.functions/janitor.add_column.md, janitor.functions/janitor.add_columns.md, janitor.functions/janitor.bin_numeric.md, janitor.functions/janitor.change_type.md, ..., reference/janitor.functions/janitor.transform_column.md, reference/janitor.functions/janitor.transform_columns.md, reference/janitor.functions/janitor.update_where.md, reference/janitor.spark.functions/janitor.spark.clean_names.md, reference/janitor.spark.functions/janitor.spark.update_where.md, reference/janitor.xarray.functions/janitor.xarray.clone_using.md, reference/janitor.xarray.functions/janitor.xarray.convert_datetime_to_number.md, reference/ml.rst, reference/pyspark.rst, reference/xarray.rst Killed make: *** [Makefile:20: html] Error 137

[ericmjl]

Hi @samukweku, thanks for being so thorough with the checks!

This seems to be a sphinx error, but there's a lack of detail in the trace that Sphinx has provided. From a bit of quick googling, it looks a bit like a memory issue to me, but my prior assumption on devs' computers is that usually there's more than enough locally (8GB RAM seems to be standard nowadays), so I'm not sure what might be causing the issue. Do you think you could report back on the hardware specs of your dev machine, just so that we can rule out that it is an issue with memory?

If you're having issues with building the docs, don't worry, I have a rough Sphinx linter in my head that I can make sure to put to good use when reviewing your examples. Also, if you grant me the right permissions on GitHub (look out for "allow maintainers to push to branch" or something analogous), I should be able to pull down your branch and build docs locally.

Thankfully, we also have a CI system that can be your fallback for performing all the checks. If you submit the PR before doing any of the checks locally, that won't be a problem. We have instructions for local checks mostly to just save you time discovering bugs and/or code style issues (because the CI system takes a bit of time to run through all of the checks).

[samukweku]

made some commits to the pull request @ericmjl. hopefully i'm getting the hang of it.

[ericmjl]

hopefully i'm getting the hang of it.

@samukweku I know you will! :smile:

made some commits to the pull request

I think they still have yet to be pushed up. No worries - let's take the discussion to the PR thread on this.

[VPerrollaz]

I am not entirely sure if it is related but I saw a few functions

• functions.filter_date
• functions.add_column
• functions.currency_column_to_numeric who have not (or very minimal) example in the docstring, but just below the docstring have comments starting with # TODO: convert this to a notebook. In which case should we indeed turn this in notebooks, or convert to docstring examples or both?