Document bootstrap and initialization hooks

Fix #2616

_pytest/hookspec.py

@@ -85,8 +85,7 @@ def pytest_configure(config):
 
 # -------------------------------------------------------------------------
 # Bootstrapping hooks called for plugins registered early enough:
-# internal and 3rd party plugins as well as directly
-# discoverable conftest.py local plugins.
+# internal and 3rd party plugins.
 # -------------------------------------------------------------------------
 
 
@@ -96,6 +95,9 @@ def pytest_cmdline_parse(pluginmanager, args):
 
     Stops at first non-None result, see :ref:`firstresult`
 
+    .. note::
+        This hook will not be called for ``conftest.py`` files, only for setuptools plugins.
+
     :param _pytest.config.PytestPluginManager pluginmanager: pytest plugin manager
     :param list[str] args: list of arguments passed on the command line
     """
@@ -107,6 +109,9 @@ def pytest_cmdline_preparse(config, args):
     This hook is considered deprecated and will be removed in a future pytest version. Consider
     using :func:`pytest_load_initial_conftests` instead.
 
+    .. note::
+        This hook will not be called for ``conftest.py`` files, only for setuptools plugins.
+
     :param _pytest.config.Config config: pytest config object
     :param list[str] args: list of arguments passed on the command line
     """
@@ -117,6 +122,9 @@ def pytest_cmdline_main(config):
     """ called for performing the main command line action. The default
     implementation will invoke the configure hooks and runtest_mainloop.
 
+    .. note::
+        This hook will not be called for ``conftest.py`` files, only for setuptools plugins.
+
     Stops at first non-None result, see :ref:`firstresult`
 
     :param _pytest.config.Config config: pytest config object
@@ -127,6 +135,9 @@ def pytest_load_initial_conftests(early_config, parser, args):
     """ implements the loading of initial conftest files ahead
     of command line option parsing.
 
+    .. note::
+        This hook will not be called for ``conftest.py`` files, only for setuptools plugins.
+
     :param _pytest.config.Config early_config: pytest config object
     :param list[str] args: list of arguments passed on the command line
     :param _pytest.config.Parser parser: to add command line options

doc/en/writing_plugins.rst

@@ -583,11 +583,22 @@ pytest hook reference
 Initialization, command line and configuration hooks
 ----------------------------------------------------
 
+Bootstrapping hooks
+~~~~~~~~~~~~~~~~~~~
+
+Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
+
 .. autofunction:: pytest_load_initial_conftests
 .. autofunction:: pytest_cmdline_preparse
 .. autofunction:: pytest_cmdline_parse
-.. autofunction:: pytest_addoption
 .. autofunction:: pytest_cmdline_main
+
+Initialization hooks
+~~~~~~~~~~~~~~~~~~~~
+
+Initialization hooks called for plugins and ``conftest.py`` files.
+
+.. autofunction:: pytest_addoption
 .. autofunction:: pytest_configure
 .. autofunction:: pytest_unconfigure