Replace reStructuredText pydocs for Google Format

[Benardi]

Description

As reStructuredText pydocs can be hard to read it would be nice to replace them with pydocstring in the Google Format. Also, it's necessary to ensure the project's documentation can still be generated.

Files

• touvlo/supv/* - Supervised module
• touvlo/unsupv/* - Unsupervised module
• touvlo/utils - Utils module
• docs/source/conf.py - sphinx configuration file

Tasks

Include specific tasks in the order they need to be done in. Include links to specific lines of code where the task should happen at.

• [ ] Replace reStructuredText pydocstrings for Google style pydocstrings.
• [ ] If necessary, config sphinx to generate docs using new pydocstrings format.

[reillysiemens]

@Benardi: If I understand what you're asking for correctly, I'd like to take a stab at this.

Do you mean you want docstrings like

def p(x, threshold=0.5):
    """Predicts whether a probability falls into class 1.

    :param x: Probability that example belongs to class 1.
    :type x: obj

    :param threshold: point above which a probability is deemed of class 1.
    :type threshold: float

    :returns: Binary value to denote class 1 or 0
    :rtype: int
    """

to be transformed into

def p(x, threshold=0.5):
    """Predicts whether a probability falls into class 1.

    Args:
        x (obj): Probability that example belongs to class 1.
        threshold (float): Point above which a probability is deemed of class 1.

    Returns:
        int: Binary value to denote class 1 or 0.
    """

?

It looks like this tool is Python 3 only. Are you open to using type annotations? There's a Sphinx plugin that can merge type annotations with Google style docstrings. The resulting docstrings/function signatures look like this:

def p(x: obj, threshold: float = 0.5) -> int:
    """Predicts whether a probability falls into class 1.

    Args:
        x: Probability that example belongs to class 1.
        threshold: Point above which a probability is deemed of class 1.

    Returns:
        Binary value to denote class 1 or 0.
    """

[Benardi]

The project support Python 3.5 onward, so your suggestion is quite reasonable.