add warnings about caching interfering with changes to settings and plugins

docs/content.rst

@@ -95,6 +95,13 @@ not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
 to ``False``.  When parsing dates given in the page metadata, Pelican supports
 the W3C's `suggested subset ISO 8601`__.
 
+.. warning::
+
+   When experimenting with different settings (especially the metadata
+   ones) caching may interfere and the changes may not be visible. In
+   such cases disable caching with ``LOAD_CONTENT_CACHE = False`` or
+   use the ``--ignore-cache`` command-line switch.
+
 __ `W3C ISO 8601`_
 
 ``modified`` should be last time you updated the article, and defaults to ``date`` if not specified.

docs/faq.rst

@@ -32,6 +32,14 @@ Configuration files are optional and are just an easy way to configure Pelican.
 For basic operations, it's possible to specify options while invoking Pelican
 via the command line. See ``pelican --help`` for more information.
 
+Changes to the setting file take no effect
+==========================================
+
+When experimenting with different settings (especially the metadata
+ones) caching may interfere and the changes may not be visible. In
+such cases disable caching with ``LOAD_CONTENT_CACHE = False`` or
+use the ``--ignore-cache`` command-line switch.
+
 I'm creating my own theme. How do I use Pygments for syntax highlighting?
 =========================================================================
 

docs/plugins.rst

@@ -20,6 +20,14 @@ Alternatively, another method is to import them and add them to the list::
     from package import myplugin
     PLUGINS = [myplugin,]
 
+.. warning::
+
+   When experimenting with different plugins (especially the ones that
+   deal with metadata and content) caching may interfere and the
+   changes may not be visible. In such cases disable caching with
+   ``LOAD_CONTENT_CACHE = False`` or use the ``--ignore-cache``
+   command-line switch.
+
 If your plugins are not in an importable path, you can specify a list of paths
 via the ``PLUGIN_PATHS`` setting. As shown in the following example, paths in
 the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::

docs/settings.rst

@@ -9,6 +9,13 @@ the command line::
 (If you used the ``pelican-quickstart`` command, your primary settings file will
 be named ``pelicanconf.py`` by default.)
 
+.. warning::
+
+   When experimenting with different settings (especially the metadata
+   ones) caching may interfere and the changes may not be visible. In
+   such cases disable caching with ``LOAD_CONTENT_CACHE = False`` or
+   use the ``--ignore-cache`` command-line switch.
+
 Settings are configured in the form of a Python module (a file). There is an
 `example settings file
 <https://github.com/getpelican/pelican/raw/master/samples/pelican.conf.py>`_