Skip to content

Commit

Permalink
[doc framework] Assert that the good and bad example exists in the doc (
Browse files Browse the repository at this point in the history
  • Loading branch information
Pierre-Sassoulas authored Sep 20, 2024
1 parent 7aa4436 commit bd97b93
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 12 deletions.
3 changes: 0 additions & 3 deletions doc/data/messages/u/unrecognize-option/details.rst

This file was deleted.

4 changes: 3 additions & 1 deletion doc/data/messages/u/unrecognized-option/details.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@ One of your options is not recognized. There's nothing to change in
your code, but your pylint configuration or the way you launch
pylint needs to be modified.

For example you might be launching pylint with the following ``toml`` configuration::
For example, this message would be raised when invoking pylint with
``pylint --unknown-option=yes test.py``. Or you might be launching
pylint with the following ``toml`` configuration::

[tool.pylint]
jars = "10"
Expand Down
41 changes: 33 additions & 8 deletions doc/exts/pylint_messages.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,27 @@

MSG_TYPES_DOC = {k: v if v != "info" else "information" for k, v in MSG_TYPES.items()}

MESSAGES_WITHOUT_EXAMPLES = {
"astroid-error", # internal
"bad-configuration-section", # configuration
"bad-plugin-value", # internal
"c-extension-no-member", # not easy to implement in the current doc framework
"config-parse-error", # configuration
"fatal", # internal
"import-self", # not easy to implement in the current doc framework
"invalid-character-nul", # not easy to implement in the current doc framework
"invalid-characters-in-docstring", # internal in py-enchant
"invalid-unicode-codec", # placeholder (not implemented yet)
"method-check-failed", # internal
"parse-error", # internal
"raw-checker-failed", # internal
"unrecognized-option", # configuration
}
MESSAGES_WITHOUT_BAD_EXAMPLES = {
"invalid-character-carriage-return", # can't be raised in normal pylint use
"return-arg-in-generator", # can't be raised in modern python
}


class MessageData(NamedTuple):
checker: str
Expand Down Expand Up @@ -99,6 +120,11 @@ def _get_pylintrc_code(data_path: Path) -> str:

def _get_demo_code_for(data_path: Path, example_type: ExampleType) -> str:
"""Get code examples while handling multi-file code templates."""
if data_path.name in MESSAGES_WITHOUT_EXAMPLES or (
data_path.name in MESSAGES_WITHOUT_BAD_EXAMPLES
and example_type is ExampleType.BAD
):
return ""
single_file_path = data_path / f"{example_type.value}.py"
multiple_code_path = data_path / f"{example_type.value}"

Expand Down Expand Up @@ -130,8 +156,9 @@ def _get_demo_code_for(data_path: Path, example_type: ExampleType) -> str:
"""
)
return _get_titled_rst(title=title, text="\n".join(files))

return ""
raise AssertionError(
f"Please add a {example_type.value} code example for {data_path}"
)


def _check_placeholders(
Expand Down Expand Up @@ -187,9 +214,7 @@ def _get_ini_as_rst(code_path: Path) -> str:
"""


def _get_all_messages(
linter: PyLinter,
) -> tuple[MessagesDict, OldMessagesDict]:
def _get_all_messages(linter: PyLinter) -> tuple[MessagesDict, OldMessagesDict]:
"""Get all messages registered to a linter and return a dictionary indexed by
message type.
Expand Down Expand Up @@ -241,8 +266,8 @@ def _get_all_messages(
if message.old_names:
for old_name in message.old_names:
category = MSG_TYPES_DOC[old_name[0][0]]
# We check if the message is already in old_messages so
# we don't duplicate shared messages.
# We check if the message is already in old_messages, so we don't
# duplicate shared messages.
if (message.symbol, msg_type) not in old_messages[category][
(old_name[1], old_name[0])
]:
Expand Down Expand Up @@ -328,7 +353,7 @@ def _generate_single_message_body(message: MessageData) -> str:
"""

body += "\n" + message.example_code + "\n"
body += f"\n{message.example_code}\n"

if message.checker_module_name.startswith("pylint.extensions."):
body += f"""
Expand Down

0 comments on commit bd97b93

Please sign in to comment.