Provide FAQ section in the README file

README.rst

@@ -91,3 +91,14 @@ If you use the ``-r`` flag in your requirements text file with more than one lev
 (in other words, one file includes another, the included file includes yet another, and so on),
 add the ``--requirements-max-depth`` option to flake8 (for example, ``--requirements-max-depth=3``
 to allow three levels of recursion).
+
+FAQ
+---
+
+| **Q:** Package is added to the requirements, but flake8 still reports "I900 '<NAME>' not listed
+         as a requirement".
+| **A:** It happens when the name of the package is not the same as the name of the module. In such
+         a case, you have to provide the mapping between the package name and the module name. See
+         the "`Customization <#customization>`_" section for more details. If the package for which
+         that happens is a well-known package, please fill out a bug report or add mapping to the
+         `KNOWN_3RD_PARTIES <src/flake8_requirements/modules.py#L509>`_ and submit a pull request.

src/flake8_requirements/checker.py

@@ -305,6 +305,9 @@ class Flake8Checker(object):
     # Host-based mapping for 3rd party modules.
     known_host_3rd_parties = {}
 
+    # Collect and report I901 errors
+    error_I901_enabled = False
+
     # User defined project->modules mapping.
     known_modules = {}
 
@@ -338,8 +341,7 @@ def add_options(cls, manager):
                 " provided modules. For example: ``--known-modules=project:"
                 "[Project],extra-project:[extras,utilities]``."
             ),
-            **kw
-        )
+            **kw)
         manager.add_option(
             "--requirements-file",
             action='store',
@@ -350,8 +352,7 @@ def add_options(cls, manager):
                 "given, requirements from setup.py, setup.cfg or "
                 "pyproject.toml will not be taken into account."
             ),
-            **kw
-        )
+            **kw)
         manager.add_option(
             "--requirements-max-depth",
             type=int if flake8.__version__ >= '3.8.0' else 'int',
@@ -360,8 +361,7 @@ def add_options(cls, manager):
                 "Max depth to resolve recursive requirements. Defaults to 1 "
                 "(one level of recursion allowed)."
             ),
-            **kw
-        )
+            **kw)
         manager.add_option(
             "--scan-host-site-packages",
             action='store_true',
@@ -370,8 +370,7 @@ def add_options(cls, manager):
                 "which provide more than one module or the name of the module"
                 " is different than the project name itself."
             ),
-            **kw
-        )
+            **kw)
 
     @classmethod
     def parse_options(cls, options):
@@ -740,8 +739,9 @@ def run(self):
 
         checkers = []
         checkers.append(self.check_I900)
-        checkers.append(self.check_I901)
+        if self.error_I901_enabled:
+            checkers.append(self.check_I901)
 
         for node in ImportVisitor(self.tree).imports:
             for err in filter(None, map(lambda c: c(node), checkers)):
-                yield (node.line, node.offset, err, Flake8Checker)
+                yield node.line, node.offset, err, type(self)