pylint docstring checker 不工作原因及可能的解决方案

[SigureMo]

问题描述 Please describe your issue

目前 Paddle 的 pre-commit hooks 里是有 pylint 的，见

Paddle/.pre-commit-config.yaml

Lines 77 to 84 in 7c30253

	- repo: local
	hooks:
	- id: pylint-doc-string
	name: pylint
	description: Check python docstring style using docstring_checker.
	entry: bash ./tools/codestyle/pylint_pre_commit.hook
	language: system
	files: \.(py)$

这是一个 local hook，hook 源码见

Paddle/tools/codestyle/pylint_pre_commit.hook

Lines 1 to 25 in 7e91438

	#!/bin/bash
	TOTAL_ERRORS=0
	DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
	export PYTHONPATH=$DIR:$PYTHONPATH
	readonly VERSION="2.12.0"
	version=$(pylint --version | grep 'pylint')
	if ! [[ $version == *"$VERSION"* ]]; then
	pip install pylint==2.12.0
	fi
	# The trick to remove deleted files: https://stackoverflow.com/a/2413151
	for file in $(git diff --name-status | awk '$1 != "D" {print $2}'); do
	pylint --disable=all --load-plugins=docstring_checker \
	--enable=doc-string-one-line,doc-string-end-with,doc-string-with-all-args,doc-string-triple-quotes,doc-string-missing,doc-string-indent-error,doc-string-with-returns,doc-string-with-raises $file;
	TOTAL_ERRORS=$(expr $TOTAL_ERRORS + $?);
	done
	exit $TOTAL_ERRORS
	#For now, just warning:
	#exit 0

其实就是关闭所有的 pylint 内置规则，仅仅启用了本地自己写的 docstring_checker 规则

https://github.com/PaddlePaddle/Paddle/blob/develop/tools/codestyle/docstring_checker.py

具体规则可见：

Paddle/tools/codestyle/docstring_checker.py

Lines 122 to 159 in 7e91438

	msgs = {
	'W9001': (
	'One line doc string on > 1 lines',
	symbol + "-one-line",
	'Used when a short doc string is on multiple lines',
	),
	'W9002': (
	'Doc string does not end with "." period',
	symbol + "-end-with",
	'Used when a doc string does not end with a period',
	),
	'W9003': (
	'All args with their types must be mentioned in doc string %s',
	symbol + "-with-all-args",
	'Used when not all arguments are in the doc string ',
	),
	'W9005': (
	'Missing docstring or docstring is too short',
	symbol + "-missing",
	'Add docstring longer >=10',
	),
	'W9006': (
	'Docstring indent error, use 4 space for indent',
	symbol + "-indent-error",
	'Use 4 space for indent',
	),
	'W9007': (
	'You should add `Returns` in comments',
	symbol + "-with-returns",
	'There should be a `Returns` section in comments',
	),
	'W9008': (
	'You should add `Raises` section in comments',
	symbol + "-with-raises",
	'There should be a `Raises` section in comments',
	),
	}
	options = ()

简单来说就是对函数有无 docstring、docstring 长度、包含字段等等做出了一些限制（比如含 return 语句的函数、类其 docstring 必须包含 Returns 字段，包含 raise 语句的则必须包含 Raises 等等，其实这个已经与现有的文档规范不一致了）

该 hook 于 #9848 最开始引入并在本地仅起到提示的作用，而在 #11351 正式启用，当时应该是可以在 CI 正确拦截有问题的 docstring 的

之后不清楚什么时候 CI 逻辑修改了导致该 hook 在 CI 上完全失效，cpplint hook 也有相似问题（见 #46102 (comment) ），这个问题在 #46136 修复了，其实 cpplint 问题还好，至少本地是 work 的，只是 CI 不 work 而已，而 pylint hook 因为直接使用 git diff 获得改动的文件，在 git 工作区干净的情况下是不会有任何输出的，而我们 commit 时绝大多数情况工作区都是干净的，简单来说，就是本地、CI 基本都不 work

因此 pylint docstring 的存量问题……很吓人，我们可以通过以下方式大概看一下存量：

pip install pylint==2.12.0
cd tools/codestyle
pylint --disable=all --load-plugins=docstring_checker \
    --enable=doc-string-one-line,doc-string-end-with,doc-string-with-all-args,doc-string-triple-quotes,doc-string-missing,doc-string-indent-error,doc-string-with-returns,doc-string-with-raises ../../python

唔，也就 17000+ 行输出吧……

这样的话直接启用肯定不可取，但如果修改一下脚本也许可以考虑一下，比如：

• 单测不需要强制有 docstring
• 强制有 Raises 可以删除或者改成强制没有 Raises
• fluid 目录也可以暂时不管，像 flake8 做的那样
• 等等等等

或者我们可以考虑直接按照新的需求重写一下

不过就算启用，修存量也是一件痛苦的事情，对于 docstring，我还没有找到一个比较合适的自动化修复工具，这意味着可能很大程度依赖于手动修复 / 自己写脚本

此外说一个算是有点相关的问题，Call-for-contribution - IDEA：iScan 流水线退场 中提到了可能会考虑 PR-CI-iScan-Python 的替代方式，如果考虑在 pre-commit 中的 pylint 来替代的话，就需要考虑开启其他规则，因此想要用 pylint 替代该流水线可能需要先修复下 pylint hook 的问题

[paddle-bot]

您好，我们已经收到了您的问题，会安排技术人员尽快解答您的问题，请耐心等待。请您再次检查是否提供了清晰的问题描述、复现代码、环境&版本、报错信息等。同时，您也可以通过查看官网API文档、常见问题、历史Issue、AI社区来寻求解答。祝您生活愉快～

Hi! We've received your issue and please be patient to get responded. We will arrange technicians to answer your questions as soon as possible. Please make sure that you have posted enough message to demo your request. You may also check out the API，FAQ，Github Issue and AI community to get the answer.Have a nice day!

[SigureMo]

@Ligoml 这里我整理了下 pylint 存在的问题及可能的修复方式，可能对规范 docstring 格式 / 内容有所帮助

PS: 这个原本是想和 cpplint 一起修的，flake8 tracking issue 里也一直放着这个的 TODO，但也因为上面所说的，存量很难修，所以暂时没有管

[Ligoml]

收到，很有用的信息~

[jzhang533]

So sad to know this. :(

除了在pre-commit阶段做检查之外，我们另外一个值得做的事情是吧doctest 或者 xdoctest，这类工具引入到paddle。相比于现在我们的流水线中，简单的把示例代码抽取出来，直接运行，看是否运行成功的检查来说，这类工具能提供更加灵活（如：运行前设置不同的运行环境），更精准的测试（直接检查运行出来的结果是否符合设定的预期）。