Merge pull request #1030 from Rogdham/filter_log

Limit and filter logs

docs/contribute.rst

@@ -143,3 +143,41 @@ and Python 3 at the same time:
   changed it where I felt necessary.
 
 - Changed xrange() back to range(), so it is valid in both Python versions.
+
+
+Logging tips
+============
+
+Try to use logging with appropriate levels.
+
+For logging messages that are not repeated, use the usual Python way:
+
+    # at top of file
+    import logging
+    logger = logging.getLogger(__name__)
+
+    # when needed
+    logger.warning('A warning that could occur only once")
+
+However, if you want to log messages that may occur several times, instead of
+a string, gives a tuple to the logging method, with two arguments:
+
+ 1. The message to log for this very execution
+ 2. A generic message that will appear if the previous one would occur to many
+    times.
+
+For example, if you want to log missing resources, use the following code:
+
+    for ressource in ressources:
+        if ressource.is_missing:
+            logger.warning((
+                'The resource {r} is missing'.format(r=ressource.name),
+                'Other resources were missing'))
+
+The logs will be displayed as follows:
+
+    WARNING: The resource prettiest_cat.jpg is missing
+    WARNING: The resource best_cat_ever.jpg is missing
+    WARNING: The resource cutest_cat.jpg is missing
+    WARNING: The resource lolcat.jpg is missing
+    WARNING: Other resources were missing

docs/settings.rst

@@ -88,6 +88,9 @@ Setting name (default value)
                                                                                  here or a single string representing one locale.
                                                                                  When providing a list, all the locales will be tried
                                                                                  until one works.
+`LOG_FILTER` (``[]``)                                                            A list of tuples containing the logging level (up to warning)
+                                                                                 and the message to be ignored.
+                                                                                 For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]``
 `READERS` (``{}``)                                                               A dictionary of file extensions / Reader classes for Pelican to
                                                                                  process or ignore. For example, to avoid processing .html files,
                                                                                  set: ``READERS = {'html': None}``. To add a custom reader for the
@@ -694,6 +697,23 @@ adding the following to your configuration::
 
     CSS_FILE = "wide.css"
 
+
+Logging
+=======
+
+Sometimes, useless lines of log appears while the generation occurs. Finding
+**the** meaningful error message in the middle of tons of annoying log outputs
+can be quite tricky. To be able to filter out all useless log messages, Pelican
+comes with the ``LOG_FILTER`` setting.
+
+``LOG_FILTER`` should be a list of tuples ``(level, msg)``, each of them being
+composed of the logging level (up to warning) and the message to be ignored.
+Simply populate the list with the logs you want to hide and they will be
+filtered out.
+
+For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]``
+
+
 Example settings
 ================