From f2ec249a9a5d969ec24f99d81fe33fabdab619ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Fri, 18 Mar 2022 16:39:55 +0100 Subject: [PATCH 1/4] Set up system of code examples and details for message documentation --- .pre-commit-config.yaml | 2 +- doc/conf.py | 2 +- doc/data/messages/e/empty-docstring/bad.py | 2 + doc/data/messages/e/empty-docstring/good.py | 2 + .../y/yield-inside-async-function/bad.py | 2 + .../y/yield-inside-async-function/details.rst | 1 + .../y/yield-inside-async-function/good.py | 7 ++ .../y/yield-inside-async-function/related.rst | 1 + doc/exts/pylint_messages.py | 73 ++++++++++++++++++- 9 files changed, 89 insertions(+), 3 deletions(-) create mode 100644 doc/data/messages/e/empty-docstring/bad.py create mode 100644 doc/data/messages/e/empty-docstring/good.py create mode 100644 doc/data/messages/y/yield-inside-async-function/bad.py create mode 100644 doc/data/messages/y/yield-inside-async-function/details.rst create mode 100644 doc/data/messages/y/yield-inside-async-function/good.py create mode 100644 doc/data/messages/y/yield-inside-async-function/related.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6df441d822..fa9e2249a5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -13,7 +13,7 @@ repos: rev: v1.4 hooks: - id: autoflake - exclude: &fixtures tests/functional/|tests/input|tests/regrtest_data/|tests/data/ + exclude: &fixtures tests/functional/|tests/input|tests/regrtest_data/|tests/data/|doc/data/messages args: - --in-place - --remove-all-unused-imports diff --git a/doc/conf.py b/doc/conf.py index 1c44c89c67..0f15ffd91c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -73,7 +73,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ["_build"] +exclude_patterns = ["_build", "data/**"] # The reST default role (used for this markup: `text`) to use for all documents. # default_role = None diff --git a/doc/data/messages/e/empty-docstring/bad.py b/doc/data/messages/e/empty-docstring/bad.py new file mode 100644 index 0000000000..83d3601251 --- /dev/null +++ b/doc/data/messages/e/empty-docstring/bad.py @@ -0,0 +1,2 @@ +def foo(): + pass # [emtpy-docstring] diff --git a/doc/data/messages/e/empty-docstring/good.py b/doc/data/messages/e/empty-docstring/good.py new file mode 100644 index 0000000000..b587ca4c6c --- /dev/null +++ b/doc/data/messages/e/empty-docstring/good.py @@ -0,0 +1,2 @@ +def foo(): + """A dummy description.""" diff --git a/doc/data/messages/y/yield-inside-async-function/bad.py b/doc/data/messages/y/yield-inside-async-function/bad.py new file mode 100644 index 0000000000..6e1d6bd28b --- /dev/null +++ b/doc/data/messages/y/yield-inside-async-function/bad.py @@ -0,0 +1,2 @@ +async def foo(): + yield from [1, 2, 3] # [yield-inside-async-function] diff --git a/doc/data/messages/y/yield-inside-async-function/details.rst b/doc/data/messages/y/yield-inside-async-function/details.rst new file mode 100644 index 0000000000..030256a450 --- /dev/null +++ b/doc/data/messages/y/yield-inside-async-function/details.rst @@ -0,0 +1 @@ +THe message can't be emitted when using Python < 3.5. diff --git a/doc/data/messages/y/yield-inside-async-function/good.py b/doc/data/messages/y/yield-inside-async-function/good.py new file mode 100644 index 0000000000..1af96506b5 --- /dev/null +++ b/doc/data/messages/y/yield-inside-async-function/good.py @@ -0,0 +1,7 @@ +async def foo(): + def _inner_foo(): + yield from [1, 2, 3] + + +async def foo(): + yield 42 diff --git a/doc/data/messages/y/yield-inside-async-function/related.rst b/doc/data/messages/y/yield-inside-async-function/related.rst new file mode 100644 index 0000000000..98cb4e3a92 --- /dev/null +++ b/doc/data/messages/y/yield-inside-async-function/related.rst @@ -0,0 +1 @@ +- `PEP 525 `_ diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index 7f910918f4..e78a04cadc 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -23,6 +23,8 @@ PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages" """Path to the messages documentation folder.""" +PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages" +"""Path to the messages documentation folder.""" MSG_TYPES_DOC = {k: v if v != "info" else "information" for k, v in MSG_TYPES.items()} @@ -32,6 +34,10 @@ class MessageData(NamedTuple): id: str name: str definition: MessageDefinition + good_code: str + bad_code: str + details: str + related_links: str MessagesDict = Dict[str, List[MessageData]] @@ -47,6 +53,54 @@ def _register_all_checkers_and_extensions(linter: PyLinter) -> None: initialize_extensions(linter) +def _get_message_data(data_path: Path) -> Tuple[str, str, str]: + """Get the message data from the specified path.""" + good_code, bad_code, details, related = "", "", "", "" + + if not data_path.exists(): + return good_code, bad_code, details, related + + if (data_path / "good.py").exists(): + with open(data_path / "good.py") as file: + file_content = file.readlines() + indented_file_content = "".join(" " + i for i in file_content) + good_code = f""" +**Correct code:** + +.. code-block:: python + +{indented_file_content}""" + + if (data_path / "bad.py").exists(): + with open(data_path / "bad.py") as file: + file_content = file.readlines() + indented_file_content = "".join(" " + i for i in file_content) + bad_code = f""" +**Problematic code:** + +.. code-block:: python + +{indented_file_content}""" + + if (data_path / "details.rst").exists(): + with open(data_path / "details.rst") as file: + file_content = file.read() + related = f""" +**Additional details:** + +{file_content}""" + + if (data_path / "related.rst").exists(): + with open(data_path / "related.rst") as file: + file_content = file.read() + related = f""" +**Related links:** + +{file_content}""" + + return good_code, bad_code, details, related + + def _get_all_messages( linter: PyLinter, ) -> Tuple[MessagesDict, OldMessagesDict]: @@ -72,8 +126,20 @@ def _get_all_messages( "information": defaultdict(list), } for message in linter.msgs_store.messages: + message_data_path = ( + PYLINT_MESSAGES_DATA_PATH / message.symbol[0] / message.symbol + ) + good_code, bad_code, details, related = _get_message_data(message_data_path) + message_data = MessageData( - message.checker_name, message.msgid, message.symbol, message + message.checker_name, + message.msgid, + message.symbol, + message, + good_code, + bad_code, + details, + related, ) messages_dict[MSG_TYPES_DOC[message.msgid[0]]].append(message_data) @@ -108,6 +174,11 @@ def _write_message_page(messages_dict: MessagesDict) -> None: *{message.definition.description}* +{message.good_code} +{message.bad_code} +{message.details} +{message.related_links} + Created by ``{message.checker}`` checker """ ) From f1137f415d5a6832b96afff0640e44c9abe0b156 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Fri, 18 Mar 2022 16:50:13 +0100 Subject: [PATCH 2/4] Oops :) --- doc/exts/pylint_messages.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index e78a04cadc..8ed7376911 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -53,7 +53,7 @@ def _register_all_checkers_and_extensions(linter: PyLinter) -> None: initialize_extensions(linter) -def _get_message_data(data_path: Path) -> Tuple[str, str, str]: +def _get_message_data(data_path: Path) -> Tuple[str, str, str, str]: """Get the message data from the specified path.""" good_code, bad_code, details, related = "", "", "", "" @@ -61,7 +61,7 @@ def _get_message_data(data_path: Path) -> Tuple[str, str, str]: return good_code, bad_code, details, related if (data_path / "good.py").exists(): - with open(data_path / "good.py") as file: + with open(data_path / "good.py", encoding="utf-8") as file: file_content = file.readlines() indented_file_content = "".join(" " + i for i in file_content) good_code = f""" @@ -72,7 +72,7 @@ def _get_message_data(data_path: Path) -> Tuple[str, str, str]: {indented_file_content}""" if (data_path / "bad.py").exists(): - with open(data_path / "bad.py") as file: + with open(data_path / "bad.py", encoding="utf-8") as file: file_content = file.readlines() indented_file_content = "".join(" " + i for i in file_content) bad_code = f""" @@ -83,20 +83,20 @@ def _get_message_data(data_path: Path) -> Tuple[str, str, str]: {indented_file_content}""" if (data_path / "details.rst").exists(): - with open(data_path / "details.rst") as file: - file_content = file.read() - related = f""" + with open(data_path / "details.rst", encoding="utf-8") as file: + file_content_string = file.read() + details = f""" **Additional details:** -{file_content}""" +{file_content_string}""" if (data_path / "related.rst").exists(): - with open(data_path / "related.rst") as file: - file_content = file.read() + with open(data_path / "related.rst", encoding="utf-8") as file: + file_content_string = file.read() related = f""" **Related links:** -{file_content}""" +{file_content_string}""" return good_code, bad_code, details, related From 406648a903cff2fa865f1d916362a5fde0351490 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Fri, 18 Mar 2022 16:54:26 +0100 Subject: [PATCH 3/4] Is it THe or The... --- doc/data/messages/y/yield-inside-async-function/details.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/data/messages/y/yield-inside-async-function/details.rst b/doc/data/messages/y/yield-inside-async-function/details.rst index 030256a450..7d05701aeb 100644 --- a/doc/data/messages/y/yield-inside-async-function/details.rst +++ b/doc/data/messages/y/yield-inside-async-function/details.rst @@ -1 +1 @@ -THe message can't be emitted when using Python < 3.5. +The message can't be emitted when using Python < 3.5. From 38e3a1acb62c35a491a6847937a08f2da3640f41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Sat, 19 Mar 2022 10:00:40 +0100 Subject: [PATCH 4/4] Fixed docstring --- doc/exts/pylint_messages.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index 8ed7376911..0f9ac35de9 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -24,7 +24,7 @@ """Path to the messages documentation folder.""" PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages" -"""Path to the messages documentation folder.""" +"""Path to the folder with data for the messages documentation.""" MSG_TYPES_DOC = {k: v if v != "info" else "information" for k, v in MSG_TYPES.items()}