Skip to content

Commit 7fabf60

Browse files
kgrytekgryte
committed
Update source docs
1 parent 7103f10 commit 7fabf60

1 file changed

Lines changed: 86 additions & 22 deletions

File tree

‎tools/make/lib/lint/python/pylint.mk‎

Lines changed: 86 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,16 @@ PYLINT_FLAGS ?= \
4141

4242
# RULES #
4343

44-
# Check for Pylint.
44+
#/
45+
# Checks whether [Pylint][1] is installed.
4546
#
46-
# This target checks if Pylint is installed.
47-
47+
# [1]: https://github.com/PyCQA/pylint
48+
#
49+
# @private
50+
#
51+
# @example
52+
# make check-pylint
53+
#/
4854
check-pylint:
4955
ifeq (, $(shell command -v $(PYLINT) 2>/dev/null))
5056
$(QUIET) echo ''
@@ -59,10 +65,23 @@ endif
5965

6066
.PHONY: check-pylint
6167

62-
# Check source code quality.
68+
#/
69+
# Lints Python source code quality.
6370
#
64-
# This target lints only Python source files.
65-
71+
# ## Notes
72+
#
73+
# - This rule is useful when wanting to glob for Python source files (e.g., lint all Python source files for a particular package).
74+
#
75+
# @private
76+
# @param {string} [PYTHON_SOURCES_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
77+
# @param {*} [FAST_FAIL] - flag indicating whether to stop linting upon encountering a lint error
78+
#
79+
# @example
80+
# make pylint-src
81+
#
82+
# @example
83+
# make pylint-src PYTHON_SOURCES_FILTER=.*/math/base/special/abs/.*
84+
#/
6685
pylint-src:
6786
ifeq ($(FAIL_FAST), true)
6887
$(QUIET) $(FIND_PYTHON_SOURCES_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
@@ -80,11 +99,23 @@ endif
8099

81100
.PHONY: pylint-src
82101

83-
84-
# Check test fixture code quality.
102+
#/
103+
# Lints Python test fixture code quality.
85104
#
86-
# This target lints only Python test fixture files.
87-
105+
# ## Notes
106+
#
107+
# - This rule is useful when wanting to glob for Python test fixture files (e.g., lint all Python test fixture files for a particular package).
108+
#
109+
# @private
110+
# @param {string} [TESTS_FIXTURES_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
111+
# @param {*} [FAST_FAIL] - flag indicating whether to stop linting upon encountering a lint error
112+
#
113+
# @example
114+
# make pylint-tests-fixtures
115+
#
116+
# @example
117+
# make pylint-tests-fixtures PYTHON_TESTS_FIXTURES_FILTER=.*/math/base/special/abs/.*
118+
#/
88119
pylint-tests-fixtures:
89120
ifeq ($(FAIL_FAST), true)
90121
$(QUIET) $(FIND_PYTHON_TESTS_FIXTURES_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
@@ -102,11 +133,23 @@ endif
102133

103134
.PHONY: pylint-tests-fixtures
104135

105-
106-
# Check example code quality.
136+
#/
137+
# Lints Python examples code quality.
107138
#
108-
# This target lints only Python example files.
109-
139+
# ## Notes
140+
#
141+
# - This rule is useful when wanting to glob for Python examples files (e.g., lint all Python examples files for a particular package).
142+
#
143+
# @private
144+
# @param {string} [PYTHON_EXAMPLES_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
145+
# @param {*} [FAST_FAIL] - flag indicating whether to stop linting upon encountering a lint error
146+
#
147+
# @example
148+
# make pylint-examples
149+
#
150+
# @example
151+
# make pylint-examples PYTHON_EXAMPLES_FILTER=.*/math/base/special/abs/.*
152+
#/
110153
pylint-examples:
111154
ifeq ($(FAIL_FAST), true)
112155
$(QUIET) $(FIND_PYTHON_EXAMPLES_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
@@ -124,11 +167,23 @@ endif
124167

125168
.PHONY: pylint-examples
126169

127-
128-
# Check benchmark code quality.
170+
#/
171+
# Lints Python benchmark code quality.
129172
#
130-
# This target lints only Python benchmark files.
131-
173+
# ## Notes
174+
#
175+
# - This rule is useful when wanting to glob for Python benchmark files (e.g., lint all Python benchmark files for a particular package).
176+
#
177+
# @private
178+
# @param {string} [PYTHON_BENCHMARKS_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
179+
# @param {*} [FAST_FAIL] - flag indicating whether to stop linting upon encountering a lint error
180+
#
181+
# @example
182+
# make pylint-benchmarks
183+
#
184+
# @example
185+
# make pylint-benchmarks PYTHON_BENCHMARKS_FILTER=.*/math/base/special/abs/.*
186+
#/
132187
pylint-benchmarks:
133188
ifeq ($(FAIL_FAST), true)
134189
$(QUIET) $(FIND_PYTHON_BENCHMARKS_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
@@ -146,11 +201,20 @@ endif
146201

147202
.PHONY: pylint-benchmarks
148203

149-
150-
# Check Python code quality.
204+
#/
205+
# Lints code quality for a specified list of Python files.
151206
#
152-
# This target lints Python files. Note that we expect `$FILES` to be a Python file list.
153-
207+
# ## Notes
208+
#
209+
# - This rule is useful when wanting to lint a list of Python files generated by some other command (e.g., a list of changed Python files obtained via `git diff`).
210+
#
211+
# @private
212+
# @param {string} FILES - list of Python file paths
213+
# @param {*} [FAST_FAIL] - flag indicating whether to stop linting upon encountering a lint error
214+
#
215+
# @example
216+
# make pylint-files FILES='/foo/file.py /bar/file.py'
217+
#/
154218
pylint-files:
155219
ifeq ($(FAIL_FAST), true)
156220
$(QUIET) for file in $(FILES); do \

0 commit comments

Comments
 (0)