Update logging docs with the new changes in 3.4

Ref: #3013

1 files changed, 75 insertions, 31 deletions

diff --git a/doc/en/logging.rst b/doc/en/logging.rst
index 9a6df8484..534ac5687 100644
--- a/doc/en/logging.rst
+++ b/doc/en/logging.rst
@@ -3,21 +3,8 @@
 Logging
 -------
 
-.. versionadded 3.3.0
-
-.. note::
-
-   This feature is a drop-in replacement for the `pytest-catchlog
-   <https://pypi.org/project/pytest-catchlog/>`_ plugin and they will conflict
-   with each other. The backward compatibility API with ``pytest-capturelog``
-   has been dropped when this feature was introduced, so if for that reason you
-   still need ``pytest-catchlog`` you can disable the internal feature by
-   adding to your ``pytest.ini``:
-
-   .. code-block:: ini
-
-       [pytest]
-           addopts=-p no:logging
+.. versionadded:: 3.3
+.. versionchanged:: 3.4
 
 Log messages are captured by default and for each failed test will be shown in
 the same manner as captured stdout and stderr.
@@ -29,7 +16,7 @@ Running without options::
 Shows failed tests like so::
 
     ----------------------- Captured stdlog call ----------------------
-    test_reporting.py    26 INFO     text going to logger
+    test_reporting.py    26 WARNING  text going to logger
     ----------------------- Captured stdout call ----------------------
     text going to stdout
     ----------------------- Captured stderr call ----------------------
@@ -49,7 +36,7 @@ Running pytest specifying formatting options::
 Shows failed tests like so::
 
     ----------------------- Captured stdlog call ----------------------
-    2010-04-10 14:48:44 INFO text going to logger
+    2010-04-10 14:48:44 WARNING text going to logger
     ----------------------- Captured stdout call ----------------------
     text going to stdout
     ----------------------- Captured stderr call ----------------------
@@ -92,7 +79,7 @@ messages.  This is supported by the ``caplog`` fixture::
         caplog.set_level(logging.INFO)
         pass
 
-By default the level is set on the handler used to catch the log messages,
+By default the level is set on the root logger,
 however as a convenience it is also possible to set the log level of any
 logger::
 
@@ -100,14 +87,16 @@ logger::
         caplog.set_level(logging.CRITICAL, logger='root.baz')
         pass
 
+The log levels set are restored automatically at the end of the test.
+
 It is also possible to use a context manager to temporarily change the log
-level::
+level inside a ``with`` block::
 
     def test_bar(caplog):
         with caplog.at_level(logging.INFO):
             pass
 
-Again, by default the level of the handler is affected but the level of any
+Again, by default the level of the root logger is affected but the level of any
 logger can be changed instead with::
 
     def test_bar(caplog):
@@ -115,7 +104,7 @@ logger can be changed instead with::
             pass
 
 Lastly all the logs sent to the logger during the test run are made available on
-the fixture in the form of both the LogRecord instances and the final log text.
+the fixture in the form of both the ``logging.LogRecord`` instances and the final log text.
 This is useful for when you want to assert on the contents of a message::
 
     def test_baz(caplog):
@@ -146,12 +135,31 @@ You can call ``caplog.clear()`` to reset the captured log records in a test::
         your_test_method()
         assert ['Foo'] == [rec.message for rec in caplog.records]
 
+
+Accessing logs from other test stages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``caplop.records`` fixture contains records from the current stage only. So
+inside the setup phase it contains only setup logs, same with the call and
+teardown phases. To access logs from other stages you can use
+``caplog.get_handler('setup').records``. Valid stages are ``setup``, ``call``
+and ``teardown``.
+
+
+.. _live_logs:
+
+
+caplog fixture API
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: _pytest.logging.LogCaptureFixture
+    :members:
+
 Live Logs
 ^^^^^^^^^
 
-By default, pytest will output any logging records with a level higher or
-equal to WARNING. In order to actually see these logs in the console you have to
-disable pytest output capture by passing ``-s``.
+By setting the :confval:`log_cli` configuration option to ``true``, pytest will output
+logging records as they are emitted directly into the console.
 
 You can specify the logging level for which log records with equal or higher
 level are printed to the console by passing ``--log-cli-level``. This setting
@@ -191,11 +199,47 @@ option names are:
 * ``log_file_format``
 * ``log_file_date_format``
 
-Accessing logs from other test stages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _log_release_notes:
 
-The ``caplop.records`` fixture contains records from the current stage only. So
-inside the setup phase it contains only setup logs, same with the call and
-teardown phases. To access logs from other stages you can use
-``caplog.get_handler('setup').records``. Valid stages are ``setup``, ``call``
-and ``teardown``.
+Release notes
+^^^^^^^^^^^^^
+
+This feature was introduced as a drop-in replacement for the `pytest-catchlog
+<https://pypi.org/project/pytest-catchlog/>`_ plugin and they conflict
+with each other. The backward compatibility API with ``pytest-capturelog``
+has been dropped when this feature was introduced, so if for that reason you
+still need ``pytest-catchlog`` you can disable the internal feature by
+adding to your ``pytest.ini``:
+
+.. code-block:: ini
+
+   [pytest]
+       addopts=-p no:logging
+
+
+.. _log_changes_3_4:
+
+Incompatible changes in pytest 3.4
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This feature was introduced in ``3.3`` and some **incompatible changes** have been
+made in ``3.4`` after community feedback:
+
+* Log levels are no longer changed unless explicitly requested by the :confval:`log_level` configuration
+  or ``--log-level`` command-line options. This allows users to configure logger objects themselves.
+* :ref:`Live Logs <live_logs>` is now disabled by default and can be enabled setting the
+  :confval:`log_cli` configuration option to ``true``.
+* :ref:`Live Logs <live_logs>` are now sent to ``sys.stdout`` and no longer require the ``-s`` command-line option
+  to work.
+
+If you want to partially restore the logging behavior of version ``3.3``, you can add this options to your ``ini``
+file:
+
+.. code-block:: ini
+
+    [pytest]
+    log_cli=true
+    log_level=NOTSET
+
+More details about the discussion that lead to this changes can be read in
+issue `#3013 <https://github.com/pytest-dev/pytest/issues/3013>`_.