airflow icon indicating copy to clipboard operation
airflow copied to clipboard

Enable More PyDocStyle Checks

Open kaxil opened this issue 3 years ago • 64 comments

~~We use PyDocStyle in pre-commit to enforce docstring style~~

We use Ruff to enforce docsting style https://github.com/apache/airflow/blob/23b8e839a35e84d57c5cf38b0b21171ac3bd1ecc/pyproject.toml#L47-L74

We follow pep257 style (http://www.pydocstyle.org/en/stable/error_codes.html) for checks.

Currently, we ignore the following rules:

The task is to complete the following missing rules:

Missing Docstrings

  • [ ] D100 | Missing docstring in public module
  • [ ] D102 | Missing docstring in public method
  • [ ] D104 | Missing docstring in public package
  • ~[ ] D105 | Missing docstring in magic method~ : As discussed in https://lists.apache.org/thread/8jbg1dd2lr2cfydtqbjxsd6pb6q2wkc3, https://github.com/apache/airflow/pull/38452 - we remove the D105 rule from our checks.
  • [ ] D107 | Missing docstring in __init__

Whitespace Issues

  • [x] D200 | One-line docstring should fit on one line with quotes -- (https://github.com/apache/airflow/pull/11688)
  • [x] D202 | No blank lines allowed after function docstring -- (https://github.com/apache/airflow/pull/11032)
  • [x] D204 | 1 blank line required after class docstring -- (https://github.com/apache/airflow/pull/11031)
  • [x] D205 | 1 blank line required between summary line and description

Docstring Content Issues

  • [x] D400 | First line should end with a period
  • [x] D401 | First line should be in imperative mood https://github.com/apache/airflow/issues/37256

It would be good if we can enable them one by one -- separate PRs are ok

Let me know if you need any help

kaxil avatar Sep 05 '20 01:09 kaxil