Refactor docstrings to Google standard format

[roedoejet]

This was brought up in PR https://github.com/dhdaines/ReadAlong-Studio/pull/8 - I think we should adopt some kind of standard for docstrings, for the sake of documentation and integration with Sphinx as well as just general consistency. The numpy standard was proposed.

[dhdaines]

This seems reasonable. I've usually used the Google standard which is a bit more compact but I think the numpy one might be a little easier to write.

One thing I would like is that instead of a big comment block at the top of the file we should use module-level docstrings, as these are actually accessible to code, etc, rather than only readable by humans.

[roedoejet]

I'm happy to use the Google standard too. @littell @joanise any preferences?

Google:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Numpy

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

[joanise]

My top concern would be consistency throughout. Either is fine, although Google requires less typing and is a bit easier to read when looked at in the plain text source. So my vote is a slight preference for Google style.

[roedoejet]

I'm happy with Google then too. I changed the title of this issue.

[joanise]

I just added missing documentation for the bare option to align_audio() and I notice that despite this ticket here, we're still using Numpy style. Is it still on the agenda to convert all to Google style? I'm assuming there's just not been enough time to do it.

[joanise]

Useful link to the Google python doc standard, embedded in their Python style guide: https://google.github.io/styleguide/pyguide.html See section 3.8 Comments and Docstrings.

[joanise]

Much progress has been done is this docstring conversion, but I guess it's not fully complete yet. I do it as a "drive-by" task, when I touch files for other reasons, it's less painful this way.

[joanise]

But now it's time to close this issue. There's more drive-by fixing to do, but the bulk is done.