flake8-docstringsのチェック項目の検討

[Tacha-S]

概要

D104では __init__.py にそのパッケージを説明するdocstringが書かれているかのチェックを行うが、
__init__.py にまでdocstringを書く必要があるか微妙なためignoreするかどうかを検討する。

目的

必要以上のチェックをしないようにし、開発者の負担を緩和するため

[Tacha-S]

関連
https://github.com/sbgisen/cube_python_api/pull/70

@jsupratman13
ちなみに__init__.pyにdocstring書くことでsphinxで生成されるドキュメントって何か変わりますか？

[jsupratman13]

Modules Contentのトップに__init__.pyの文章が追加されます。

[jsupratman13]

追記：__init__.pyの文章はsubmodulesには含まれません。

[Tacha-S]

追記：__init__.pyの文章はsubmodulesには含まれません。

なるほど。
ローカルで見たとき何も反映されてないかと思ったのはそのせいか...

[jsupratman13]

ドキュメント表示の話しになるけど sbgisen/cube_python_api#71

[Tacha-S]

D104に限らず、

• 日本語のドキュメントでのD415(First line should end with a period, question mark, or exclamation point)
• バックスラッシュを使用しているところでのD301(Use r""" if any backslashes in a docstring)

などがsphinxのdocument生成の成否にかかわらず警告されるので検討する。

[Tacha-S]

docstringの有無だけflake8-docstringsにまかせて、
あとはhttps://github.com/peterjc/flake8-rst-docstrings を使うというのもありかもしれません。

https://github.com/sbgisen/cube_python_api でのflake8-rst-docstrings

flake8 ./src
./src/cube_python_api/__init__.py:1:1: D104 Missing docstring in public package
./src/cube_python_api/cube_commander.py:106:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/cube_commander.py:132:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/cube_commander.py:164:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/cube_commander.py:208:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/__init__.py:1:1: D104 Missing docstring in public package
./src/cube_python_api/utils/geometry.py:39:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/geometry.py:60:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/geometry.py:129:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_generation.py:53:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_generation.py:117:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_generation.py:179:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_generation.py:181:1: RST210 Inline strong start-string without end-string.
./src/cube_python_api/utils/message_generation.py:238:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_generation.py:240:1: RST210 Inline strong start-string without end-string.
./src/cube_python_api/utils/message_generation.py:307:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_generation.py:309:1: RST210 Inline strong start-string without end-string.
./src/cube_python_api/utils/decorator.py:34:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/decorator.py:99:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/decorator.py:158:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/utils/message_conversion.py:47:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:211:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:323:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:435:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:566:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:715:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/utils/message_conversion.py:835:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/managers/move_base_manager.py:127:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/managers/__init__.py:1:1: D104 Missing docstring in public package
./src/cube_python_api/managers/battery_status_manager.py:210:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/managers/speech_manager.py:49:1: D301 Use r""" if any backslashes in a docstring
./src/cube_python_api/proxies/publisher.py:94:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/proxies/publisher.py:94:1: RST210 Inline strong start-string without end-string.
./src/cube_python_api/proxies/__init__.py:1:1: D104 Missing docstring in public package
./src/cube_python_api/proxies/service_proxy.py:83:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/proxies/service_proxy.py:83:1: RST210 Inline strong start-string without end-string.
./src/cube_python_api/proxies/service_proxy.py:114:1: RST213 Inline emphasis start-string without end-string.
./src/cube_python_api/proxies/service_proxy.py:114:1: RST210 Inline strong start-string without end-string.

RST210, 213は*args や **kwargs の *が強調表現と捉えられて片側しか無いとか中に何もないというので怒られていてまだissue段階のようですが...
peterjc/flake8-rst-docstrings#18

[jsupratman13]

一応最近docstringが以下のwarning が出てきます

英文書き方についてのwarningなのでignoreしてもいいかも