[DOC] Docstring style should be made clear in `contributing` page

Brief Description of Fix

Currently, the docs do not clearly describe the coding standards that the project probably should adhere to.

I believe this should be added to the Contributing page.

For reference, it should look something like this:

---

We recommend that you write docstrings before you write a test for the function, and that you write the test before writing the function implementation. This is an example of combining doc- and test-driven development together, to clarify what the function is intended to do before actually implementing it. Use the following example to help guide you on how to write your new function docstring properly.

def new_janitor_function(df, param1, param2):
    “””
    One line that describes what the function does.

    Further elaboration on the function. Use one or more paragraphs to do any of the following:
    1. Provide more detail on intended usage
    2. Clearly state assumptions on what the input dataframe should look like.
    3. Identify edge cases that will cause the function to raise an error.
    4. Other things that you want the end-user to know about before using the function.

    Method chaining example:

    .. code-block:: python

        df = df.new_janitor_function(param1, param2)

    Functional example:

    .. code-block:: python

        df = new_janitor_function(df, param1, param2)

    :param param1: A description of param1.
    :param param2: A description of param2.
    :return: A description of the dataframe that is returned.
    “””
    # now put your function implementation here

Relevant Context

• Link to documentation page
• Link to exact file to be edited

[shandou]

@hectormz I like that issue as well and I had the exact same questions on Friday when trying to extend a function feature (for example, it was not very clear to me at first about where the test data was loaded). If you and @ericmjl are both comfortable with me taking a stab at it, please combine the two issues. Can’t guarantee to get the skeleton examples right at first try, but I am sure you guys can help me iterate.

[ericmjl]

@shandou you caught a bug of mine!

what we are doing with the additional mark @pytest.mark.test

I used to use it to isolate just the test that I’m currently hacking on. It must have slipped into the library.

The correct way to isolate just the test that we are writing, borrowing the example above, is to do:

$ pytest -k test_shuffle

This will run only the tests that contain the substring test_shuffle. Usually that is good enough to avoid running the full test suite.

Also, I can see mypy as one of the dependencies, but I don’t see explicit use of it in the repo. Curious about whether type checker is used during CI? And how? Thanks!

mypy is used during development. I have a PR open to use mypy in CI, but I’m still not clear what we’d be checking for though. I think we can ignore mypy for the time being.