Improve docs clarity on loading custom checkers - FIXED (#7502)

* Improve docs clarity on loading custom checkers

Whilst the docs on testing custom checkers do touch on the fact the
module has to be in your load path, there are some restrictions that
were not made clear before.
Specifically, the init-hook configuration item (which is often used
explicitly to change the sys.path) is not automatically sufficient. If
the init hook is in a file, but the load-plugins argument is passed in
the CLI, then the plugins are loaded before the init-hook has run, and
so will not be imported. In this case, the failure can also be silent,
so the outcome is a lint that will simply not contain any information
from the checker, as opposed to a run that will error.
This corner case may merit fixing in a separate PR, that is to be
confirmed.

Closes #7264

Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com>

1 files changed, 22 insertions, 4 deletions

diff --git a/doc/development_guide/how_tos/custom_checkers.rst b/doc/development_guide/how_tos/custom_checkers.rst
index 7a9c567db..6d36b0ec6 100644
--- a/doc/development_guide/how_tos/custom_checkers.rst
+++ b/doc/development_guide/how_tos/custom_checkers.rst
@@ -218,10 +218,28 @@ Now we can debug our checker!
 .. Note::
 
     ``my_plugin`` refers to a module called ``my_plugin.py``.
-    This module can be made available to pylint by putting this
-    module's parent directory in your ``PYTHONPATH``
-    environment variable or by adding the ``my_plugin.py``
-    file to the ``pylint/checkers`` directory if running from source.
+    The preferred way of making this plugin available to pylint is
+    by installing it as a package. This can be done either from a packaging index like
+    ``PyPI`` or by installing it from a local source such as with ``pip install``.
+
+    Alternatively, the plugin module can be made available to pylint by
+    putting this module's parent directory in your ``PYTHONPATH``
+    environment variable.
+
+    If your pylint config has an ``init-hook`` that modifies
+    ``sys.path`` to include the module's parent directory, this
+    will also work, but only if either:
+
+    * the ``init-hook`` and the ``load-plugins`` list are both
+      defined in a configuration file, or...
+    * the ``init-hook`` is passed as a command-line argument and
+      the ``load-plugins`` list is in the configuration file
+
+    So, you cannot load a custom plugin by modifying ``sys.path`` if you
+    supply the ``init-hook`` in a configuration file, but pass the module name
+    in via ``--load-plugins`` on the command line.
+    This is because pylint loads plugins specified on command
+    line before loading any configuration from other sources.
 
 Defining a Message
 ------------------