[FEA] Consider Adding Flake8 Plugins to Catch Python Doc Errors

[mdemoret-nv]

Since the python documentation isn't built for PRs, many docstring issues get committed into the active branch and are only caught right before release. There are flake8 extensions which can check docstrings for errors and flag them during the style check.

Two extensions that I have in mind are flake8-docstrings and flake8-rst-docstrings. These can be added to flake8 with

pip install flake8-docstrings flake8-rst-docstrings

Enabling these plugins and running flake8 generates 2793 errors as of 0.19. Many of these are true positives but are overly strict for our needs. Adding the following to setup.cfg, significantly reduces the noise:

rst-roles =
    class,
    func,
    ref,
    py,
    term,
    meth,
rst-directives =
    envvar,
    exception,
extend-ignore =
    RST307,
    RST306,
    D100,
    D102,
    D400,
    D104,
    D105,
    D401,

Many of these docstring issues have been hidden by the fact that they aren't included in the Sphinx documentation. Adding these plugins would help reduce those errors in the future.

For reference, here is a sample of the output:

./python/cuml/common/doc_utils.py:9:1: RST301 Unexpected indentation.
./python/cuml/common/doc_utils.py:12:1: RST201 Block quote ends without a blank line; unexpected unindent.
./python/cuml/common/doc_utils.py:17:1: D205 1 blank line required between summary line and description
./python/cuml/common/doc_utils.py:170:1: D205 1 blank line required between summary line and description
./python/cuml/common/doc_utils.py:170:1: D412 No blank lines allowed between a section header and its content
./python/cuml/common/doc_utils.py:170:1: D409 Section underline should match the length of its name
./python/cuml/common/doc_utils.py:228:1: RST301 Unexpected indentation.
./python/cuml/common/doc_utils.py:354:1: D205 1 blank line required between summary line and description
./python/cuml/common/doc_utils.py:354:1: D300 Use """triple double quotes"""
./python/cuml/common/doc_utils.py:354:1: D301 Use r""" if any backslashes in a docstring
./python/cuml/common/doc_utils.py:354:1: D412 No blank lines allowed between a section header and its content
./python/cuml/common/doc_utils.py:354:1: D214 Section is over-indented
./python/cuml/common/doc_utils.py:354:1: D215 Section underline is over-indented
./python/cuml/common/doc_utils.py:354:1: D214 Section is over-indented
./python/cuml/common/doc_utils.py:354:1: D215 Section underline is over-indented
./python/cuml/common/doc_utils.py:366:1: RST201 Block quote ends without a blank line; unexpected unindent.
./python/cuml/common/doc_utils.py:370:1: RST401 Unexpected section title.
./python/cuml/common/doc_utils.py:385:1: RST401 Unexpected section title.
./python/cuml/common/doc_utils.py:392:1: RST203 Definition list ends without a blank line; unexpected unindent.

[github-actions[bot]]

This issue has been labeled inactive-30d due to no recent activity in the past 30 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed. This issue will be labeled inactive-90d if there is no activity in the next 60 days.

[UmashankarTriforce]

@mdemoret-nv @teju85 I wish to work on this issue! Could you please give me some pointers?

[github-actions[bot]]

This issue has been labeled inactive-90d due to no recent activity in the past 90 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed.