Logging doc (#6852)

* Add logging doc

* Foamtting

* Update docs/source/main_classes/logging.rst

* Update src/transformers/utils/logging.py

Co-authored-by: Lysandre Debut <lysandre@huggingface.co>

docs/source/index.rst

@@ -185,6 +185,7 @@ conversion utilities for the following models:
     main_classes/trainer
     main_classes/optimizer_schedules
     main_classes/processors
+    main_classes/logging
     model_doc/auto
     model_doc/encoderdecoder
     model_doc/bert

docs/source/main_classes/logging.rst

@@ -0,0 +1,44 @@
+Logging
+-------
+
+🤗 Transformers has a centralized logging system, so that you can setup the verbosity of the library easily. To
+change the level of verbosity, just use one of the direct setters. For instance, here is how to change the verbosity to
+the INFO level.
+
+.. code-block:: python
+
+    import transformers
+    transformers.logging.set_verbosity_info()
+
+All the methods of this logging module are documented below, the main ones are
+:func:`transformers.logging.get_verbosity` to get the current level of verbosity in the logger and
+:func:`transformers.logging.set_verbosity` to set the verbosity to the level of your choice. In order (from the least
+verbose to the most verbose), those levels (with their corresponding int values in parenthesis) are:
+
+- :obj:`transformers.logging.CRITICAL` or :obj:`transformers.logging.FATAL` (int value, 50): only report the most
+  critical errors.
+- :obj:`transformers.logging.ERROR` (int value, 40): only report errors.
+- :obj:`transformers.logging.WARNING` or :obj:`transformers.logging.WARN` (int value, 30): only reports error and
+  warnings. This the default level used by the library.
+- :obj:`transformers.logging.INFO` (int value, 20): reports error, warnings and basic information.
+- :obj:`transformers.logging.DEBUG` (int value, 10): report all information.
+
+Base setters
+~~~~~~~~~~~~
+
+.. autofunction:: transformers.logging.set_verbosity_error
+
+.. autofunction:: transformers.logging.set_verbosity_warning
+
+.. autofunction:: transformers.logging.set_verbosity_info
+
+.. autofunction:: transformers.logging.set_verbosity_debug
+
+Other functions
+~~~~~~~~~~~~~~~
+
+.. autofunction:: transformers.logging.get_verbosity
+
+.. autofunction:: transformers.logging.set_verbosity
+
+.. autofunction:: transformers.logging.get_logger

src/transformers/utils/logging.py

@@ -73,8 +73,10 @@ def _reset_library_root_logger() -> None:
 
 
 def get_logger(name: Optional[str] = None) -> logging.Logger:
-    """Return a logger with the specified name.
+    """
-    This function is not supposed to be directly accessed by library users.
+    Return a logger with the specified name.
+
+    This function is not supposed to be directly accessed unless you are writing a custom transformers module.
     """
 
     if name is None:
@@ -85,16 +87,21 @@ def get_logger(name: Optional[str] = None) -> logging.Logger:
 
 
 def get_verbosity() -> int:
-    """Return the current level for the HuggingFace Transformers's root logger.
+    """
+    Return the current level for the 🤗 Transformers's root logger as an int.
+
     Returns:
-        Logging level, e.g., ``transformers.logging.DEBUG`` and ``transformers.logging.INFO``.
+        :obj:`int`: The logging level.
+
     .. note::
-        HuggingFace Transformers has following logging levels:
+
-        - ``transformers.logging.CRITICAL``, ``transformers.logging.FATAL``
+        🤗 Transformers has following logging levels:
-        - ``transformers.logging.ERROR``
+
-        - ``transformers.logging.WARNING``, ``transformers.logging.WARN``
+        - 50: ``transformers.logging.CRITICAL`` or ``transformers.logging.FATAL``
-        - ``transformers.logging.INFO``
+        - 40: ``transformers.logging.ERROR``
-        - ``transformers.logging.DEBUG``
+        - 30: ``transformers.logging.WARNING`` or ``transformers.logging.WARN``
+        - 20: ``transformers.logging.INFO``
+        - 10: ``transformers.logging.DEBUG``
     """
 
     _configure_library_root_logger()
@@ -102,10 +109,18 @@ def get_verbosity() -> int:
 
 
 def set_verbosity(verbosity: int) -> None:
-    """Set the level for the HuggingFace Transformers's root logger.
+    """
+    Set the vebosity level for the 🤗 Transformers's root logger.
+
     Args:
-        verbosity:
+        verbosity (:obj:`int`):
-            Logging level, e.g., ``transformers.logging.DEBUG`` and ``transformers.logging.INFO``.
+            Logging level, e.g., one of:
+
+            - ``transformers.logging.CRITICAL`` or ``transformers.logging.FATAL``
+            - ``transformers.logging.ERROR``
+            - ``transformers.logging.WARNING`` or ``transformers.logging.WARN``
+            - ``transformers.logging.INFO``
+            - ``transformers.logging.DEBUG``
     """
 
     _configure_library_root_logger()
@@ -113,18 +128,22 @@ def set_verbosity(verbosity: int) -> None:
 
 
 def set_verbosity_info():
+    """Set the verbosity to the :obj:`INFO` level."""
     return set_verbosity(INFO)
 
 
 def set_verbosity_warning():
+    """Set the verbosity to the :obj:`WARNING` level."""
     return set_verbosity(WARNING)
 
 
 def set_verbosity_debug():
+    """Set the verbosity to the :obj:`DEBUG` level."""
     return set_verbosity(DEBUG)
 
 
 def set_verbosity_error():
+    """Set the verbosity to the :obj:`ERROR` level."""
     return set_verbosity(ERROR)