From f906a22b758a35a48deef95ce86c8e0320cedf87 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 18:01:33 +0200 Subject: [PATCH 1/6] [doc] Move all messages documentation to user_guide/messages --- .gitignore | 9 ++++- doc/Makefile | 5 +-- doc/conf.py | 3 ++ doc/exts/pylint_messages.py | 2 +- doc/index.rst | 1 - doc/messages/index.rst | 11 ------ doc/messages/messages_introduction.rst | 15 -------- doc/user_guide/index.rst | 2 +- doc/user_guide/messages/index.rst | 34 +++++++++++++++++++ .../{ => messages}/message-control.rst | 6 +--- .../messages/messages_list.rst | 0 11 files changed, 51 insertions(+), 37 deletions(-) delete mode 100644 doc/messages/index.rst delete mode 100644 doc/messages/messages_introduction.rst create mode 100644 doc/user_guide/messages/index.rst rename doc/user_guide/{ => messages}/message-control.rst (95%) rename doc/{ => user_guide}/messages/messages_list.rst (100%) diff --git a/.gitignore b/.gitignore index b4fa458beb..ea96bb6888 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,14 @@ /pylint.egg-info/ .tox *.sw[a-z] -doc/messages/ +# Can't use | operator in .gitignore, see +# https://unix.stackexchange.com/a/31806/189111 +doc/user_guide/messages/convention/ +doc/user_guide/messages/error/ +doc/user_guide/messages/fatal/ +doc/user_guide/messages/information/ +doc/user_guide/messages/refactor/ +doc/user_guide/messages/warning/ doc/technical_reference/extensions.rst doc/technical_reference/features.rst doc/user_guide/configuration/all-options.rst diff --git a/doc/Makefile b/doc/Makefile index 73ab49ae59..ee03e051e1 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -36,8 +36,9 @@ help: @echo " linkcheck to check all external links for integrity" clean: - -rm -rf $(BUILDDIR)/* messages/convention messages/error messages/fatal messages/information \ - messages/refactor messages/warning technical_reference/extensions.rst technical_reference/features.rst + -rm -rf $(BUILDDIR)/* user_guide/messages/convention user_guide/messages/error \ + user_guide/messages/fatal user_guide/messages/information user_guide/messages/refactor \ + user_guide/messages/warning technical_reference/extensions.rst technical_reference/features.rst install-dependencies: @echo "Install dependencies" diff --git a/doc/conf.py b/doc/conf.py index 63bb999762..5134ffe671 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -51,6 +51,9 @@ "intro": "index.html", "support": "contact.html", "user_guide/ide-integration": "installation.html", + "messages/index": "user_guide/messages/index.html", + "messages/messages_introduction": "user_guide/messages/index.html", + "user_guide/message-control": "user_guide/messages/message-control.html", } # Add any paths that contain templates here, relative to this directory. diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index 4388985d93..7b09f0ff66 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -23,7 +23,7 @@ PYLINT_BASE_PATH = Path(__file__).resolve().parent.parent.parent """Base path to the project folder.""" -PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages" +PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc/user_guide/messages" """Path to the messages documentation folder.""" PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages" diff --git a/doc/index.rst b/doc/index.rst index 0a77c74634..df9a4c133e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -44,7 +44,6 @@ re-evaluate and re-enable messages as your priorities evolve. tutorial user_guide/index.rst how_tos/index.rst - messages/index.rst technical_reference/index.rst development_guide/index.rst additional_commands/index.rst diff --git a/doc/messages/index.rst b/doc/messages/index.rst deleted file mode 100644 index aceca53f61..0000000000 --- a/doc/messages/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _messages: - -Messages -=================== - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - messages_introduction - messages_list diff --git a/doc/messages/messages_introduction.rst b/doc/messages/messages_introduction.rst deleted file mode 100644 index e351d1b9bd..0000000000 --- a/doc/messages/messages_introduction.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _messages-introduction: - -Message categories -===================== - -Pylint can emit various messages. These are categorized according to categories:: - - Convention - Error - Fatal - Information - Refactor - Warning - -A list of these messages can be found here: :ref:`messages-list` diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 84947b5302..739a22fa56 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -9,7 +9,7 @@ User Guide installation run output - message-control + messages/index options ide_integration/ide-integration pre-commit-integration diff --git a/doc/user_guide/messages/index.rst b/doc/user_guide/messages/index.rst new file mode 100644 index 0000000000..f21efb5390 --- /dev/null +++ b/doc/user_guide/messages/index.rst @@ -0,0 +1,34 @@ +.. _messages: + +######## +Messages +######## + +.. toctree:: + :maxdepth: 2 + :hidden: + + + messages_list.rst + message-control.rst + +Pylint can emit various messages. These are categorized according +to categories corresponding to bit-encoded exit codes: + +* :ref:`Fatal` (1) +* :ref:`Error` (2) +* :ref:`Warning` (4) +* :ref:`Convention` (8) +* :ref:`Refactor` (16) +* :ref:`Information` (NA) + +A list of these messages can be found in :ref:`messages-list` + +Disabling messages +================== + +``pylint`` has an advanced message control for its checks, offering the ability +to enable / disable a message either from the command line or from the configuration +file, as well as from the code itself. + +For more detail see :ref:`message-control` diff --git a/doc/user_guide/message-control.rst b/doc/user_guide/messages/message-control.rst similarity index 95% rename from doc/user_guide/message-control.rst rename to doc/user_guide/messages/message-control.rst index 0f735e533a..4ac6cec4b1 100644 --- a/doc/user_guide/message-control.rst +++ b/doc/user_guide/messages/message-control.rst @@ -3,11 +3,7 @@ Messages control ================ -``pylint`` has an advanced message control for its checks, offering the ability -to enable / disable a message either from the command line or from the configuration -file, as well as from the code itself. - -For all of these controls, ``pylint`` accepts the following values: +In order to control messages, ``pylint`` accepts the following values: * a symbolic message: ``no-member``, ``undefined-variable`` etc. diff --git a/doc/messages/messages_list.rst b/doc/user_guide/messages/messages_list.rst similarity index 100% rename from doc/messages/messages_list.rst rename to doc/user_guide/messages/messages_list.rst From e348d7b6fd6961ca8d2a5d3355b60677e882fe0d Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 20:05:22 +0200 Subject: [PATCH 2/6] [refactor] Better link and toc definition for overview of messages --- doc/conf.py | 1 + doc/exts/pylint_messages.py | 31 +- doc/user_guide/messages/index.rst | 20 +- doc/user_guide/messages/messages_list.rst | 539 ----------------- doc/user_guide/messages/messages_overview.rst | 549 ++++++++++++++++++ 5 files changed, 579 insertions(+), 561 deletions(-) delete mode 100644 doc/user_guide/messages/messages_list.rst create mode 100644 doc/user_guide/messages/messages_overview.rst diff --git a/doc/conf.py b/doc/conf.py index 5134ffe671..226873b6b3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -53,6 +53,7 @@ "user_guide/ide-integration": "installation.html", "messages/index": "user_guide/messages/index.html", "messages/messages_introduction": "user_guide/messages/index.html", + "messages/messages_list": "user_guide/messages/messages_overview.html", "user_guide/message-control": "user_guide/messages/message-control.html", } diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index 7b09f0ff66..c1404fa2ff 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -230,7 +230,8 @@ def _write_single_message_page(category_dir: Path, message: MessageData) -> None stream.write( f""" .. note:: - This message is emitted by an optional checker which requires the ``{message.checker_module_name}`` plugin to be loaded. See: :ref:`{message.checker_module_name}`. + This message is emitted by an optional checker which requires the ``{message.checker_module_name}`` + plugin to be loaded. See: :ref:`{message.checker_module_name}`. """ ) @@ -244,22 +245,24 @@ def _write_messages_list_page( messages_dict: MessagesDict, old_messages_dict: OldMessagesDict ) -> None: """Create or overwrite the page with the list of all messages.""" - messages_file = os.path.join(PYLINT_MESSAGES_PATH, "messages_list.rst") + messages_file = os.path.join(PYLINT_MESSAGES_PATH, "messages_overview.rst") with open(messages_file, "w", encoding="utf-8") as stream: # Write header of file + title = "Messages overview" stream.write( - f""".. _messages-list: + f""" +.. _messages-overview: -{get_rst_title("Overview of all Pylint messages", "=")} +{"#" * len(title)} +{get_rst_title(title, "#")} .. NOTE This file is auto-generated. Make any changes to the associated - docs extension in 'pylint_messages.py'. + docs extension in 'doc/exts/pylint_messages.py'. Pylint can emit the following messages: """ ) - # Iterate over tuple to keep same order for category in ( "fatal", @@ -272,15 +275,19 @@ def _write_messages_list_page( messages = sorted(messages_dict[category], key=lambda item: item.name) old_messages = sorted(old_messages_dict[category], key=lambda item: item[0]) messages_string = "".join( - f" {category}/{message.name}.rst\n" for message in messages + f" {category}/{message.name}\n" for message in messages ) old_messages_string = "".join( - f" {category}/{old_message[0]}.rst\n" for old_message in old_messages + f" {category}/{old_message[0]}\n" for old_message in old_messages ) - # Write list per category + # Write list per category. We need the '-category' suffix in the reference + # because 'fatal' is also a message's symbol stream.write( - f"""{get_rst_title(category.capitalize(), "-")} + f""" +.. _{category.lower()}-category: + +{get_rst_title(category.capitalize(), "*")} All messages in the {category} category: .. toctree:: @@ -294,9 +301,7 @@ def _write_messages_list_page( :maxdepth: 1 :titlesonly: -{old_messages_string} - -""" +{old_messages_string}""" ) diff --git a/doc/user_guide/messages/index.rst b/doc/user_guide/messages/index.rst index f21efb5390..0f20e8c1a5 100644 --- a/doc/user_guide/messages/index.rst +++ b/doc/user_guide/messages/index.rst @@ -8,21 +8,23 @@ Messages :maxdepth: 2 :hidden: - - messages_list.rst + messages_overview.rst message-control.rst +Messages categories +=================== + Pylint can emit various messages. These are categorized according to categories corresponding to bit-encoded exit codes: -* :ref:`Fatal` (1) -* :ref:`Error` (2) -* :ref:`Warning` (4) -* :ref:`Convention` (8) -* :ref:`Refactor` (16) -* :ref:`Information` (NA) +* :ref:`Fatal ` (1) +* :ref:`Error ` (2) +* :ref:`Warning ` (4) +* :ref:`Convention ` (8) +* :ref:`Refactor ` (16) +* :ref:`Information ` (NA) -A list of these messages can be found in :ref:`messages-list` +An overview of these messages can be found in :ref:`messages-overview` Disabling messages ================== diff --git a/doc/user_guide/messages/messages_list.rst b/doc/user_guide/messages/messages_list.rst deleted file mode 100644 index c7674dcb77..0000000000 --- a/doc/user_guide/messages/messages_list.rst +++ /dev/null @@ -1,539 +0,0 @@ -.. _messages-list: - -Overview of all Pylint messages -=============================== - -.. - NOTE This file is auto-generated. Make any changes to the associated - docs extension in 'pylint_messages.py'. - -Pylint can emit the following messages: - -Fatal ------ - -All messages in the fatal category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - fatal/astroid-error.rst - fatal/config-parse-error.rst - fatal/fatal.rst - fatal/method-check-failed.rst - fatal/parse-error.rst - -All renamed messages in the fatal category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - fatal/old-import-error.rst - - -Error ------ - -All messages in the error category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - error/abstract-class-instantiated.rst - error/access-member-before-definition.rst - error/assigning-non-slot.rst - error/assignment-from-no-return.rst - error/assignment-from-none.rst - error/await-outside-async.rst - error/bad-configuration-section.rst - error/bad-except-order.rst - error/bad-exception-context.rst - error/bad-format-character.rst - error/bad-option-value.rst - error/bad-plugin-value.rst - error/bad-reversed-sequence.rst - error/bad-str-strip-call.rst - error/bad-string-format-type.rst - error/bad-super-call.rst - error/bidirectional-unicode.rst - error/broken-collections-callable.rst - error/broken-noreturn.rst - error/catching-non-exception.rst - error/class-variable-slots-conflict.rst - error/continue-in-finally.rst - error/dict-iter-missing-items.rst - error/duplicate-argument-name.rst - error/duplicate-bases.rst - error/format-needs-mapping.rst - error/function-redefined.rst - error/import-error.rst - error/inconsistent-mro.rst - error/inherit-non-class.rst - error/init-is-generator.rst - error/invalid-all-format.rst - error/invalid-all-object.rst - error/invalid-bool-returned.rst - error/invalid-bytes-returned.rst - error/invalid-character-backspace.rst - error/invalid-character-carriage-return.rst - error/invalid-character-esc.rst - error/invalid-character-nul.rst - error/invalid-character-sub.rst - error/invalid-character-zero-width-space.rst - error/invalid-class-object.rst - error/invalid-enum-extension.rst - error/invalid-envvar-value.rst - error/invalid-format-returned.rst - error/invalid-getnewargs-ex-returned.rst - error/invalid-getnewargs-returned.rst - error/invalid-hash-returned.rst - error/invalid-index-returned.rst - error/invalid-length-hint-returned.rst - error/invalid-length-returned.rst - error/invalid-metaclass.rst - error/invalid-repr-returned.rst - error/invalid-sequence-index.rst - error/invalid-slice-index.rst - error/invalid-slots.rst - error/invalid-slots-object.rst - error/invalid-star-assignment-target.rst - error/invalid-str-returned.rst - error/invalid-unary-operand-type.rst - error/invalid-unicode-codec.rst - error/logging-format-truncated.rst - error/logging-too-few-args.rst - error/logging-too-many-args.rst - error/logging-unsupported-format.rst - error/method-hidden.rst - error/misplaced-bare-raise.rst - error/misplaced-format-function.rst - error/missing-format-string-key.rst - error/missing-kwoa.rst - error/mixed-format-string.rst - error/modified-iterating-dict.rst - error/modified-iterating-set.rst - error/no-member.rst - error/no-method-argument.rst - error/no-name-in-module.rst - error/no-self-argument.rst - error/no-value-for-parameter.rst - error/non-iterator-returned.rst - error/nonexistent-operator.rst - error/nonlocal-and-global.rst - error/nonlocal-without-binding.rst - error/not-a-mapping.rst - error/not-an-iterable.rst - error/not-async-context-manager.rst - error/not-callable.rst - error/not-context-manager.rst - error/not-in-loop.rst - error/notimplemented-raised.rst - error/potential-index-error.rst - error/raising-bad-type.rst - error/raising-non-exception.rst - error/redundant-keyword-arg.rst - error/relative-beyond-top-level.rst - error/repeated-keyword.rst - error/return-arg-in-generator.rst - error/return-in-init.rst - error/return-outside-function.rst - error/star-needs-assignment-target.rst - error/syntax-error.rst - error/too-few-format-args.rst - error/too-many-format-args.rst - error/too-many-function-args.rst - error/too-many-star-expressions.rst - error/truncated-format-string.rst - error/undefined-all-variable.rst - error/undefined-variable.rst - error/unexpected-keyword-arg.rst - error/unexpected-special-method-signature.rst - error/unhashable-dict-key.rst - error/unpacking-non-sequence.rst - error/unrecognized-inline-option.rst - error/unrecognized-option.rst - error/unsubscriptable-object.rst - error/unsupported-assignment-operation.rst - error/unsupported-binary-operation.rst - error/unsupported-delete-operation.rst - error/unsupported-membership-test.rst - error/used-before-assignment.rst - error/used-prior-global-declaration.rst - error/yield-inside-async-function.rst - error/yield-outside-function.rst - -All renamed messages in the error category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - error/bad-context-manager.rst - error/maybe-no-member.rst - error/old-non-iterator-returned-2.rst - error/old-unbalanced-tuple-unpacking.rst - - -Warning -------- - -All messages in the warning category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - warning/abstract-method.rst - warning/anomalous-backslash-in-string.rst - warning/anomalous-unicode-escape-in-string.rst - warning/arguments-differ.rst - warning/arguments-out-of-order.rst - warning/arguments-renamed.rst - warning/assert-on-string-literal.rst - warning/assert-on-tuple.rst - warning/attribute-defined-outside-init.rst - warning/bad-builtin.rst - warning/bad-format-string.rst - warning/bad-format-string-key.rst - warning/bad-indentation.rst - warning/bad-open-mode.rst - warning/bad-staticmethod-argument.rst - warning/bad-thread-instantiation.rst - warning/bare-except.rst - warning/binary-op-exception.rst - warning/boolean-datetime.rst - warning/broad-except.rst - warning/cell-var-from-loop.rst - warning/comparison-with-callable.rst - warning/confusing-with-statement.rst - warning/consider-ternary-expression.rst - warning/dangerous-default-value.rst - warning/deprecated-argument.rst - warning/deprecated-class.rst - warning/deprecated-decorator.rst - warning/deprecated-method.rst - warning/deprecated-module.rst - warning/deprecated-typing-alias.rst - warning/differing-param-doc.rst - warning/differing-type-doc.rst - warning/duplicate-except.rst - warning/duplicate-key.rst - warning/duplicate-string-formatting-argument.rst - warning/duplicate-value.rst - warning/eq-without-hash.rst - warning/eval-used.rst - warning/exec-used.rst - warning/expression-not-assigned.rst - warning/f-string-without-interpolation.rst - warning/fixme.rst - warning/forgotten-debug-statement.rst - warning/format-combined-specification.rst - warning/format-string-without-interpolation.rst - warning/global-at-module-level.rst - warning/global-statement.rst - warning/global-variable-not-assigned.rst - warning/global-variable-undefined.rst - warning/implicit-str-concat.rst - warning/import-self.rst - warning/inconsistent-quotes.rst - warning/invalid-envvar-default.rst - warning/invalid-format-index.rst - warning/invalid-overridden-method.rst - warning/isinstance-second-argument-not-valid-type.rst - warning/keyword-arg-before-vararg.rst - warning/logging-format-interpolation.rst - warning/logging-fstring-interpolation.rst - warning/logging-not-lazy.rst - warning/lost-exception.rst - warning/method-cache-max-size-none.rst - warning/misplaced-future.rst - warning/missing-any-param-doc.rst - warning/missing-format-argument-key.rst - warning/missing-format-attribute.rst - warning/missing-param-doc.rst - warning/missing-parentheses-for-call-in-test.rst - warning/missing-raises-doc.rst - warning/missing-return-doc.rst - warning/missing-return-type-doc.rst - warning/missing-type-doc.rst - warning/missing-yield-doc.rst - warning/missing-yield-type-doc.rst - warning/modified-iterating-list.rst - warning/multiple-constructor-doc.rst - warning/nan-comparison.rst - warning/non-ascii-file-name.rst - warning/non-parent-init-called.rst - warning/non-str-assignment-to-dunder-name.rst - warning/overlapping-except.rst - warning/overridden-final-method.rst - warning/pointless-statement.rst - warning/pointless-string-statement.rst - warning/possibly-unused-variable.rst - warning/preferred-module.rst - warning/protected-access.rst - warning/raise-missing-from.rst - warning/raising-format-tuple.rst - warning/redeclared-assigned-name.rst - warning/redefined-builtin.rst - warning/redefined-loop-name.rst - warning/redefined-outer-name.rst - warning/redefined-slots-in-subclass.rst - warning/redundant-returns-doc.rst - warning/redundant-u-string-prefix.rst - warning/redundant-unittest-assert.rst - warning/redundant-yields-doc.rst - warning/reimported.rst - warning/self-assigning-variable.rst - warning/self-cls-assignment.rst - warning/shallow-copy-environ.rst - warning/signature-differs.rst - warning/subclassed-final-class.rst - warning/subprocess-popen-preexec-fn.rst - warning/subprocess-run-check.rst - warning/super-init-not-called.rst - warning/super-without-brackets.rst - warning/too-many-try-statements.rst - warning/try-except-raise.rst - warning/unbalanced-tuple-unpacking.rst - warning/undefined-loop-variable.rst - warning/unnecessary-ellipsis.rst - warning/unnecessary-lambda.rst - warning/unnecessary-pass.rst - warning/unnecessary-semicolon.rst - warning/unreachable.rst - warning/unspecified-encoding.rst - warning/unused-argument.rst - warning/unused-format-string-argument.rst - warning/unused-format-string-key.rst - warning/unused-import.rst - warning/unused-private-member.rst - warning/unused-variable.rst - warning/unused-wildcard-import.rst - warning/useless-else-on-loop.rst - warning/useless-param-doc.rst - warning/useless-super-delegation.rst - warning/useless-type-doc.rst - warning/useless-with-lock.rst - warning/using-constant-test.rst - warning/using-f-string-in-unsupported-version.rst - warning/using-final-decorator-in-unsupported-version.rst - warning/while-used.rst - warning/wildcard-import.rst - warning/wrong-exception-operation.rst - -All renamed messages in the warning category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - warning/cache-max-size-none.rst - warning/implicit-str-concat-in-sequence.rst - warning/lru-cache-decorating-method.rst - warning/old-assignment-from-none.rst - warning/old-empty-docstring.rst - warning/old-missing-param-doc.rst - warning/old-missing-returns-doc.rst - warning/old-missing-type-doc.rst - warning/old-missing-yields-doc.rst - warning/old-non-iterator-returned-1.rst - warning/old-unidiomatic-typecheck.rst - warning/old-unpacking-non-sequence.rst - - -Convention ----------- - -All messages in the convention category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - convention/bad-classmethod-argument.rst - convention/bad-docstring-quotes.rst - convention/bad-file-encoding.rst - convention/bad-mcs-classmethod-argument.rst - convention/bad-mcs-method-argument.rst - convention/compare-to-empty-string.rst - convention/compare-to-zero.rst - convention/consider-iterating-dictionary.rst - convention/consider-using-any-or-all.rst - convention/consider-using-dict-items.rst - convention/consider-using-enumerate.rst - convention/consider-using-f-string.rst - convention/disallowed-name.rst - convention/docstring-first-line-empty.rst - convention/empty-docstring.rst - convention/import-outside-toplevel.rst - convention/import-private-name.rst - convention/invalid-characters-in-docstring.rst - convention/invalid-name.rst - convention/line-too-long.rst - convention/misplaced-comparison-constant.rst - convention/missing-class-docstring.rst - convention/missing-final-newline.rst - convention/missing-function-docstring.rst - convention/missing-module-docstring.rst - convention/mixed-line-endings.rst - convention/multiple-imports.rst - convention/multiple-statements.rst - convention/non-ascii-module-import.rst - convention/non-ascii-name.rst - convention/single-string-used-for-slots.rst - convention/singleton-comparison.rst - convention/superfluous-parens.rst - convention/too-many-lines.rst - convention/trailing-newlines.rst - convention/trailing-whitespace.rst - convention/typevar-double-variance.rst - convention/typevar-name-incorrect-variance.rst - convention/typevar-name-mismatch.rst - convention/unexpected-line-ending-format.rst - convention/ungrouped-imports.rst - convention/unidiomatic-typecheck.rst - convention/unnecessary-direct-lambda-call.rst - convention/unnecessary-dunder-call.rst - convention/unnecessary-lambda-assignment.rst - convention/unneeded-not.rst - convention/use-implicit-booleaness-not-comparison.rst - convention/use-implicit-booleaness-not-len.rst - convention/use-maxsplit-arg.rst - convention/use-sequence-for-iteration.rst - convention/useless-import-alias.rst - convention/wrong-import-order.rst - convention/wrong-import-position.rst - convention/wrong-spelling-in-comment.rst - convention/wrong-spelling-in-docstring.rst - -All renamed messages in the convention category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - convention/blacklisted-name.rst - convention/len-as-condition.rst - convention/missing-docstring.rst - convention/old-misplaced-comparison-constant.rst - convention/old-non-ascii-name.rst - - -Refactor --------- - -All messages in the refactor category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - refactor/chained-comparison.rst - refactor/comparison-of-constants.rst - refactor/comparison-with-itself.rst - refactor/condition-evals-to-constant.rst - refactor/confusing-consecutive-elif.rst - refactor/consider-alternative-union-syntax.rst - refactor/consider-merging-isinstance.rst - refactor/consider-swap-variables.rst - refactor/consider-using-alias.rst - refactor/consider-using-assignment-expr.rst - refactor/consider-using-dict-comprehension.rst - refactor/consider-using-from-import.rst - refactor/consider-using-generator.rst - refactor/consider-using-get.rst - refactor/consider-using-in.rst - refactor/consider-using-join.rst - refactor/consider-using-max-builtin.rst - refactor/consider-using-min-builtin.rst - refactor/consider-using-namedtuple-or-dataclass.rst - refactor/consider-using-set-comprehension.rst - refactor/consider-using-sys-exit.rst - refactor/consider-using-ternary.rst - refactor/consider-using-tuple.rst - refactor/consider-using-with.rst - refactor/cyclic-import.rst - refactor/duplicate-code.rst - refactor/else-if-used.rst - refactor/empty-comment.rst - refactor/inconsistent-return-statements.rst - refactor/literal-comparison.rst - refactor/no-classmethod-decorator.rst - refactor/no-else-break.rst - refactor/no-else-continue.rst - refactor/no-else-raise.rst - refactor/no-else-return.rst - refactor/no-self-use.rst - refactor/no-staticmethod-decorator.rst - refactor/property-with-parameters.rst - refactor/redefined-argument-from-local.rst - refactor/redefined-variable-type.rst - refactor/simplifiable-condition.rst - refactor/simplifiable-if-expression.rst - refactor/simplifiable-if-statement.rst - refactor/simplify-boolean-expression.rst - refactor/stop-iteration-return.rst - refactor/super-with-arguments.rst - refactor/too-complex.rst - refactor/too-few-public-methods.rst - refactor/too-many-ancestors.rst - refactor/too-many-arguments.rst - refactor/too-many-boolean-expressions.rst - refactor/too-many-branches.rst - refactor/too-many-instance-attributes.rst - refactor/too-many-locals.rst - refactor/too-many-nested-blocks.rst - refactor/too-many-public-methods.rst - refactor/too-many-return-statements.rst - refactor/too-many-statements.rst - refactor/trailing-comma-tuple.rst - refactor/unnecessary-comprehension.rst - refactor/unnecessary-dict-index-lookup.rst - refactor/unnecessary-list-index-lookup.rst - refactor/use-a-generator.rst - refactor/use-dict-literal.rst - refactor/use-list-literal.rst - refactor/use-set-for-membership.rst - refactor/useless-object-inheritance.rst - refactor/useless-return.rst - -All renamed messages in the refactor category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - refactor/old-no-self-use.rst - refactor/old-simplifiable-if-statement.rst - refactor/old-too-many-nested-blocks.rst - - -Information ------------ - -All messages in the information category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - information/bad-inline-option.rst - information/c-extension-no-member.rst - information/deprecated-pragma.rst - information/file-ignored.rst - information/locally-disabled.rst - information/raw-checker-failed.rst - information/suppressed-message.rst - information/use-symbolic-message-instead.rst - information/useless-suppression.rst - -All renamed messages in the information category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - information/deprecated-disable-all.rst diff --git a/doc/user_guide/messages/messages_overview.rst b/doc/user_guide/messages/messages_overview.rst new file mode 100644 index 0000000000..0484dbd5e4 --- /dev/null +++ b/doc/user_guide/messages/messages_overview.rst @@ -0,0 +1,549 @@ + +.. _messages-overview: + +################# +Messages overview +################# + +.. + NOTE This file is auto-generated. Make any changes to the associated + docs extension in 'doc/exts/pylint_messages.py'. + +Pylint can emit the following messages: + + +.. _fatal-category: + +Fatal +***** + +All messages in the fatal category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + fatal/astroid-error + fatal/config-parse-error + fatal/fatal + fatal/method-check-failed + fatal/parse-error + +All renamed messages in the fatal category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + fatal/old-import-error + +.. _error-category: + +Error +***** + +All messages in the error category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + error/abstract-class-instantiated + error/access-member-before-definition + error/assigning-non-slot + error/assignment-from-no-return + error/assignment-from-none + error/await-outside-async + error/bad-configuration-section + error/bad-except-order + error/bad-exception-context + error/bad-format-character + error/bad-option-value + error/bad-plugin-value + error/bad-reversed-sequence + error/bad-str-strip-call + error/bad-string-format-type + error/bad-super-call + error/bidirectional-unicode + error/broken-collections-callable + error/broken-noreturn + error/catching-non-exception + error/class-variable-slots-conflict + error/continue-in-finally + error/dict-iter-missing-items + error/duplicate-argument-name + error/duplicate-bases + error/format-needs-mapping + error/function-redefined + error/import-error + error/inconsistent-mro + error/inherit-non-class + error/init-is-generator + error/invalid-all-format + error/invalid-all-object + error/invalid-bool-returned + error/invalid-bytes-returned + error/invalid-character-backspace + error/invalid-character-carriage-return + error/invalid-character-esc + error/invalid-character-nul + error/invalid-character-sub + error/invalid-character-zero-width-space + error/invalid-class-object + error/invalid-enum-extension + error/invalid-envvar-value + error/invalid-format-returned + error/invalid-getnewargs-ex-returned + error/invalid-getnewargs-returned + error/invalid-hash-returned + error/invalid-index-returned + error/invalid-length-hint-returned + error/invalid-length-returned + error/invalid-metaclass + error/invalid-repr-returned + error/invalid-sequence-index + error/invalid-slice-index + error/invalid-slots + error/invalid-slots-object + error/invalid-star-assignment-target + error/invalid-str-returned + error/invalid-unary-operand-type + error/invalid-unicode-codec + error/logging-format-truncated + error/logging-too-few-args + error/logging-too-many-args + error/logging-unsupported-format + error/method-hidden + error/misplaced-bare-raise + error/misplaced-format-function + error/missing-format-string-key + error/missing-kwoa + error/mixed-format-string + error/modified-iterating-dict + error/modified-iterating-set + error/no-member + error/no-method-argument + error/no-name-in-module + error/no-self-argument + error/no-value-for-parameter + error/non-iterator-returned + error/nonexistent-operator + error/nonlocal-and-global + error/nonlocal-without-binding + error/not-a-mapping + error/not-an-iterable + error/not-async-context-manager + error/not-callable + error/not-context-manager + error/not-in-loop + error/notimplemented-raised + error/potential-index-error + error/raising-bad-type + error/raising-non-exception + error/redundant-keyword-arg + error/relative-beyond-top-level + error/repeated-keyword + error/return-arg-in-generator + error/return-in-init + error/return-outside-function + error/star-needs-assignment-target + error/syntax-error + error/too-few-format-args + error/too-many-format-args + error/too-many-function-args + error/too-many-star-expressions + error/truncated-format-string + error/undefined-all-variable + error/undefined-variable + error/unexpected-keyword-arg + error/unexpected-special-method-signature + error/unhashable-dict-key + error/unpacking-non-sequence + error/unrecognized-inline-option + error/unrecognized-option + error/unsubscriptable-object + error/unsupported-assignment-operation + error/unsupported-binary-operation + error/unsupported-delete-operation + error/unsupported-membership-test + error/used-before-assignment + error/used-prior-global-declaration + error/yield-inside-async-function + error/yield-outside-function + +All renamed messages in the error category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + error/bad-context-manager + error/maybe-no-member + error/old-non-iterator-returned-2 + error/old-unbalanced-tuple-unpacking + +.. _warning-category: + +Warning +******* + +All messages in the warning category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + warning/abstract-method + warning/anomalous-backslash-in-string + warning/anomalous-unicode-escape-in-string + warning/arguments-differ + warning/arguments-out-of-order + warning/arguments-renamed + warning/assert-on-string-literal + warning/assert-on-tuple + warning/attribute-defined-outside-init + warning/bad-builtin + warning/bad-format-string + warning/bad-format-string-key + warning/bad-indentation + warning/bad-open-mode + warning/bad-staticmethod-argument + warning/bad-thread-instantiation + warning/bare-except + warning/binary-op-exception + warning/boolean-datetime + warning/broad-except + warning/cell-var-from-loop + warning/comparison-with-callable + warning/confusing-with-statement + warning/consider-ternary-expression + warning/dangerous-default-value + warning/deprecated-argument + warning/deprecated-class + warning/deprecated-decorator + warning/deprecated-method + warning/deprecated-module + warning/deprecated-typing-alias + warning/differing-param-doc + warning/differing-type-doc + warning/duplicate-except + warning/duplicate-key + warning/duplicate-string-formatting-argument + warning/duplicate-value + warning/eq-without-hash + warning/eval-used + warning/exec-used + warning/expression-not-assigned + warning/f-string-without-interpolation + warning/fixme + warning/forgotten-debug-statement + warning/format-combined-specification + warning/format-string-without-interpolation + warning/global-at-module-level + warning/global-statement + warning/global-variable-not-assigned + warning/global-variable-undefined + warning/implicit-str-concat + warning/import-self + warning/inconsistent-quotes + warning/invalid-envvar-default + warning/invalid-format-index + warning/invalid-overridden-method + warning/isinstance-second-argument-not-valid-type + warning/keyword-arg-before-vararg + warning/logging-format-interpolation + warning/logging-fstring-interpolation + warning/logging-not-lazy + warning/lost-exception + warning/method-cache-max-size-none + warning/misplaced-future + warning/missing-any-param-doc + warning/missing-format-argument-key + warning/missing-format-attribute + warning/missing-param-doc + warning/missing-parentheses-for-call-in-test + warning/missing-raises-doc + warning/missing-return-doc + warning/missing-return-type-doc + warning/missing-type-doc + warning/missing-yield-doc + warning/missing-yield-type-doc + warning/modified-iterating-list + warning/multiple-constructor-doc + warning/nan-comparison + warning/non-ascii-file-name + warning/non-parent-init-called + warning/non-str-assignment-to-dunder-name + warning/overlapping-except + warning/overridden-final-method + warning/pointless-statement + warning/pointless-string-statement + warning/possibly-unused-variable + warning/preferred-module + warning/protected-access + warning/raise-missing-from + warning/raising-format-tuple + warning/redeclared-assigned-name + warning/redefined-builtin + warning/redefined-loop-name + warning/redefined-outer-name + warning/redefined-slots-in-subclass + warning/redundant-returns-doc + warning/redundant-u-string-prefix + warning/redundant-unittest-assert + warning/redundant-yields-doc + warning/reimported + warning/self-assigning-variable + warning/self-cls-assignment + warning/shallow-copy-environ + warning/signature-differs + warning/subclassed-final-class + warning/subprocess-popen-preexec-fn + warning/subprocess-run-check + warning/super-init-not-called + warning/super-without-brackets + warning/too-many-try-statements + warning/try-except-raise + warning/unbalanced-tuple-unpacking + warning/undefined-loop-variable + warning/unnecessary-ellipsis + warning/unnecessary-lambda + warning/unnecessary-pass + warning/unnecessary-semicolon + warning/unreachable + warning/unspecified-encoding + warning/unused-argument + warning/unused-format-string-argument + warning/unused-format-string-key + warning/unused-import + warning/unused-private-member + warning/unused-variable + warning/unused-wildcard-import + warning/useless-else-on-loop + warning/useless-param-doc + warning/useless-super-delegation + warning/useless-type-doc + warning/useless-with-lock + warning/using-constant-test + warning/using-f-string-in-unsupported-version + warning/using-final-decorator-in-unsupported-version + warning/while-used + warning/wildcard-import + warning/wrong-exception-operation + +All renamed messages in the warning category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + warning/cache-max-size-none + warning/implicit-str-concat-in-sequence + warning/lru-cache-decorating-method + warning/old-assignment-from-none + warning/old-empty-docstring + warning/old-missing-param-doc + warning/old-missing-returns-doc + warning/old-missing-type-doc + warning/old-missing-yields-doc + warning/old-non-iterator-returned-1 + warning/old-unidiomatic-typecheck + warning/old-unpacking-non-sequence + +.. _convention-category: + +Convention +********** + +All messages in the convention category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + convention/bad-classmethod-argument + convention/bad-docstring-quotes + convention/bad-file-encoding + convention/bad-mcs-classmethod-argument + convention/bad-mcs-method-argument + convention/compare-to-empty-string + convention/compare-to-zero + convention/consider-iterating-dictionary + convention/consider-using-any-or-all + convention/consider-using-dict-items + convention/consider-using-enumerate + convention/consider-using-f-string + convention/disallowed-name + convention/docstring-first-line-empty + convention/empty-docstring + convention/import-outside-toplevel + convention/import-private-name + convention/invalid-characters-in-docstring + convention/invalid-name + convention/line-too-long + convention/misplaced-comparison-constant + convention/missing-class-docstring + convention/missing-final-newline + convention/missing-function-docstring + convention/missing-module-docstring + convention/mixed-line-endings + convention/multiple-imports + convention/multiple-statements + convention/non-ascii-module-import + convention/non-ascii-name + convention/single-string-used-for-slots + convention/singleton-comparison + convention/superfluous-parens + convention/too-many-lines + convention/trailing-newlines + convention/trailing-whitespace + convention/typevar-double-variance + convention/typevar-name-incorrect-variance + convention/typevar-name-mismatch + convention/unexpected-line-ending-format + convention/ungrouped-imports + convention/unidiomatic-typecheck + convention/unnecessary-direct-lambda-call + convention/unnecessary-dunder-call + convention/unnecessary-lambda-assignment + convention/unneeded-not + convention/use-implicit-booleaness-not-comparison + convention/use-implicit-booleaness-not-len + convention/use-maxsplit-arg + convention/use-sequence-for-iteration + convention/useless-import-alias + convention/wrong-import-order + convention/wrong-import-position + convention/wrong-spelling-in-comment + convention/wrong-spelling-in-docstring + +All renamed messages in the convention category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + convention/blacklisted-name + convention/len-as-condition + convention/missing-docstring + convention/old-misplaced-comparison-constant + convention/old-non-ascii-name + +.. _refactor-category: + +Refactor +******** + +All messages in the refactor category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + refactor/chained-comparison + refactor/comparison-of-constants + refactor/comparison-with-itself + refactor/condition-evals-to-constant + refactor/confusing-consecutive-elif + refactor/consider-alternative-union-syntax + refactor/consider-merging-isinstance + refactor/consider-swap-variables + refactor/consider-using-alias + refactor/consider-using-assignment-expr + refactor/consider-using-dict-comprehension + refactor/consider-using-from-import + refactor/consider-using-generator + refactor/consider-using-get + refactor/consider-using-in + refactor/consider-using-join + refactor/consider-using-max-builtin + refactor/consider-using-min-builtin + refactor/consider-using-namedtuple-or-dataclass + refactor/consider-using-set-comprehension + refactor/consider-using-sys-exit + refactor/consider-using-ternary + refactor/consider-using-tuple + refactor/consider-using-with + refactor/cyclic-import + refactor/duplicate-code + refactor/else-if-used + refactor/empty-comment + refactor/inconsistent-return-statements + refactor/literal-comparison + refactor/no-classmethod-decorator + refactor/no-else-break + refactor/no-else-continue + refactor/no-else-raise + refactor/no-else-return + refactor/no-self-use + refactor/no-staticmethod-decorator + refactor/property-with-parameters + refactor/redefined-argument-from-local + refactor/redefined-variable-type + refactor/simplifiable-condition + refactor/simplifiable-if-expression + refactor/simplifiable-if-statement + refactor/simplify-boolean-expression + refactor/stop-iteration-return + refactor/super-with-arguments + refactor/too-complex + refactor/too-few-public-methods + refactor/too-many-ancestors + refactor/too-many-arguments + refactor/too-many-boolean-expressions + refactor/too-many-branches + refactor/too-many-instance-attributes + refactor/too-many-locals + refactor/too-many-nested-blocks + refactor/too-many-public-methods + refactor/too-many-return-statements + refactor/too-many-statements + refactor/trailing-comma-tuple + refactor/unnecessary-comprehension + refactor/unnecessary-dict-index-lookup + refactor/unnecessary-list-index-lookup + refactor/use-a-generator + refactor/use-dict-literal + refactor/use-list-literal + refactor/use-set-for-membership + refactor/useless-object-inheritance + refactor/useless-return + +All renamed messages in the refactor category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + refactor/old-no-self-use + refactor/old-simplifiable-if-statement + refactor/old-too-many-nested-blocks + +.. _information-category: + +Information +*********** + +All messages in the information category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + information/bad-inline-option + information/c-extension-no-member + information/deprecated-pragma + information/file-ignored + information/locally-disabled + information/raw-checker-failed + information/suppressed-message + information/use-symbolic-message-instead + information/useless-suppression + +All renamed messages in the information category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + information/deprecated-disable-all From e85540c017e657d2bc02c2242b558dbe96e00f8b Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 20:16:18 +0200 Subject: [PATCH 3/6] [doc] Remove unwanted quotation in code example for message control --- doc/user_guide/messages/message-control.rst | 72 ++++++++++----------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/doc/user_guide/messages/message-control.rst b/doc/user_guide/messages/message-control.rst index 4ac6cec4b1..5b893a31cf 100644 --- a/doc/user_guide/messages/message-control.rst +++ b/doc/user_guide/messages/message-control.rst @@ -33,63 +33,63 @@ The pragma controls can disable / enable: * All the violations on a single line - .. sourcecode:: python +.. sourcecode:: python - a, b = ... # pylint: disable=unbalanced-tuple-unpacking + a, b = ... # pylint: disable=unbalanced-tuple-unpacking * All the violations on the following line - .. sourcecode:: python +.. sourcecode:: python - # pylint: disable-next=unbalanced-tuple-unpacking - a, b = ... + # pylint: disable-next=unbalanced-tuple-unpacking + a, b = ... * All the violations in a single scope - .. sourcecode:: python +.. sourcecode:: python - def test(): - # Disable all the no-member violations in this function - # pylint: disable=no-member - ... + def test(): + # Disable all the no-member violations in this function + # pylint: disable=no-member + ... * All the violations in a `block`. For instance, each separate branch of an ``if`` statement is considered a separate block, as in the following example: - .. sourcecode:: python +.. sourcecode:: python - def meth5(self): - # pylint: disable=no-member - # no error - print(self.bla) - if self.blop: - # pylint: enable=no-member - # enable all no-members for this block - print(self.blip) - else: - # This is affected by the scope disable - print(self.blip) + def meth5(self): + # pylint: disable=no-member + # no error + print(self.bla) + if self.blop: # pylint: enable=no-member + # enable all no-members for this block + print(self.blip) + else: + # This is affected by the scope disable + print(self.blip) + # pylint: enable=no-member + print(self.blip) + if self.blop: + # pylint: disable=no-member + # disable all no-members for this block + print(self.blip) + else: + # This emits a violation print(self.blip) - if self.blop: - # pylint: disable=no-member - # disable all no-members for this block - print(self.blip) - else: - # This emits a violation - print(self.blip) * If the violation occurs on a block starting line, then it applies only to that line - .. sourcecode:: python +.. sourcecode:: python - if self.blop: # pylint: disable=no-member; applies only to this line - # Here we get an error - print(self.blip) - else: - # error - print(self.blip) + if self.blop: # pylint: disable=no-member; applies only to this line + # Here we get an error + print(self.blip) + else: + # error + print(self.blip) From 98d9a9f5eb424fc485c931201af88d5e1f852d49 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 20:50:05 +0200 Subject: [PATCH 4/6] [doc] Smaller description of the optional checker messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com> --- doc/exts/pylint_messages.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index c1404fa2ff..4a7096a710 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -230,8 +230,8 @@ def _write_single_message_page(category_dir: Path, message: MessageData) -> None stream.write( f""" .. note:: - This message is emitted by an optional checker which requires the ``{message.checker_module_name}`` - plugin to be loaded. See: :ref:`{message.checker_module_name}`. + This message is emitted by the optional :ref:`'{message.checker}'<{message.checker_module_name}>` checker which requires the ``{message.checker_module_name}`` + plugin to be loaded. """ ) From 7ade71afef6a906ba8d3c9a69ce3ded8f18a5b26 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 23:17:13 +0200 Subject: [PATCH 5/6] [doc] Modify the automated redirection to user_guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See discussion: https://github.com/PyCQA/pylint/pull/6628#discussion_r874177297 Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com> --- doc/conf.py | 9 +++++++-- doc/user_guide/index.rst | 2 +- doc/user_guide/messages/index.rst | 4 ++-- .../{message-control.rst => message_control.rst} | 0 4 files changed, 10 insertions(+), 5 deletions(-) rename doc/user_guide/messages/{message-control.rst => message_control.rst} (100%) diff --git a/doc/conf.py b/doc/conf.py index 226873b6b3..58d2ac16ef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -45,16 +45,21 @@ "sphinx_reredirects", ] + +# Single file redirects are handled in this file and can be done by a pylint +# contributor. See: # https://documatt.gitlab.io/sphinx-reredirects/usage.html +# Directory redirects are handled in ReadTheDoc admin interface and can only be done +# by pylint maintainers at the following URL: +# https://readthedocs.org/dashboard/pylint/redirects/ redirects: dict[str, str] = { # "": "" "intro": "index.html", "support": "contact.html", "user_guide/ide-integration": "installation.html", - "messages/index": "user_guide/messages/index.html", "messages/messages_introduction": "user_guide/messages/index.html", "messages/messages_list": "user_guide/messages/messages_overview.html", - "user_guide/message-control": "user_guide/messages/message-control.html", + "user_guide/message-control": "user_guide/messages/message_control.html", } # Add any paths that contain templates here, relative to this directory. diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 739a22fa56..b9c2f728aa 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -3,7 +3,7 @@ User Guide ========== .. toctree:: - :maxdepth: 3 + :maxdepth: 2 :titlesonly: installation diff --git a/doc/user_guide/messages/index.rst b/doc/user_guide/messages/index.rst index 0f20e8c1a5..f663c26c9a 100644 --- a/doc/user_guide/messages/index.rst +++ b/doc/user_guide/messages/index.rst @@ -5,11 +5,11 @@ Messages ######## .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :hidden: messages_overview.rst - message-control.rst + message_control.rst Messages categories =================== diff --git a/doc/user_guide/messages/message-control.rst b/doc/user_guide/messages/message_control.rst similarity index 100% rename from doc/user_guide/messages/message-control.rst rename to doc/user_guide/messages/message_control.rst From 7354ca0bdb4994c209fa75b7bf20fa8ef9c3094d Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Wed, 18 May 2022 13:11:06 +0200 Subject: [PATCH 6/6] [doc] Add an assertion for redirection that will silentely fail --- doc/conf.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 58d2ac16ef..25f0364b41 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -47,20 +47,28 @@ # Single file redirects are handled in this file and can be done by a pylint -# contributor. See: +# contributor if no englobing full directory redirect is applied first. See: # https://documatt.gitlab.io/sphinx-reredirects/usage.html # Directory redirects are handled in ReadTheDoc admin interface and can only be done # by pylint maintainers at the following URL: # https://readthedocs.org/dashboard/pylint/redirects/ +DIRECTORY_REDIRECT = [ + # This list has no effect it must be manually updated from the Read the doc conf + "messages/", +] redirects: dict[str, str] = { # "": "" "intro": "index.html", "support": "contact.html", "user_guide/ide-integration": "installation.html", - "messages/messages_introduction": "user_guide/messages/index.html", - "messages/messages_list": "user_guide/messages/messages_overview.html", "user_guide/message-control": "user_guide/messages/message_control.html", } +for m in redirects: + for r in DIRECTORY_REDIRECT: + assert not m.startswith(r), ( + f"Redirection will silentely fail: '{m}' start with '{r}' and " + "the whole directory is redirected by ReadtheDoc conf already." + ) # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"]