HazyResearch / fonduer

A knowledge base construction engine for richly formatted data
https://fonduer.readthedocs.io/
MIT License
409 stars 77 forks source link

Add a docstring guideline #428

Closed HiromuHota closed 4 years ago

HiromuHota commented 4 years ago

Is your feature request related to a problem? Please describe.

It'd be good to have a guideline for what the docstring should look like. The following is my work-in-progress guideline

Docstring format
^^^^^^^^^^^^^^^^

We use Sphinx as our Docstring format.
According to Sphinx, `:type` and `:rtype` are optional, but are not allowed in Fonduer.
docstring should look like as follows:

.. code-block:: python

    from typing import Union

    def format_unit(value: Union[float, int], unit: str) -> str:
        """Format the given value as a human readable string using the given units.

        :param value: a numeric value
        :param unit: the unit for the value (kg, m, etc.)
        :return: a human readable string using the given units
        """
        return '{} {}'.format(value, unit)

Describe the solution you'd like

Add a section like above to docs/dev/codestyle.rst

Describe alternatives you've considered

Use docstring style checker that can check our format. There are nice docstring checkers like pydocstyle (this can be used via flake8-docstrings), but I don't think they can check a docstring in such a detail (e.g., check if :type exists).

Additional context Add any other context or screenshots about the feature request here.

This is related to #422 and #66.