Merge pull request #795 from wking/read-file

Generate context objects in read_file()

docs/getting_started.rst

@@ -213,6 +213,8 @@ The idea behind "pages" is that they are usually not temporal in nature and are
 used for content that does not change very often (e.g., "About" or "Contact"
 pages).
 
+.. _internal_metadata:
+
 File metadata
 -------------
 

docs/plugins.rst

@@ -79,9 +79,9 @@ article_generator_finalized     article_generator               invoked at the e
 get_generators                  generators                      invoked in Pelican.get_generator_classes,
                                                                 can return a Generator, or several
                                                                 generator in a tuple or in a list.
-pages_generate_context          pages_generator, metadata
-pages_generator_init            pages_generator                 invoked in the PagesGenerator.__init__
-pages_generator_finalized       pages_generator                 invoked at the end of PagesGenerator.generate_context
+page_generate_context           page_generator, metadata
+page_generator_init             page_generator                  invoked in the PagesGenerator.__init__
+page_generator_finalized        page_generator                  invoked at the end of PagesGenerator.generate_context
 content_object_init             content_object                  invoked at the end of Content.__init__ (see note below)
 =============================   ============================   ===========================================================================
 
@@ -104,3 +104,22 @@ request if you need them!
 
        def register():
                signals.content_object_init.connect(test, sender=contents.Article)
+
+.. note::
+
+   After Pelican 3.2, signal names were standardized.  Older plugins
+   may need to be updated to use the new names:
+
+   ==========================  ===========================
+   Old name                    New name
+   ==========================  ===========================
+   article_generate_context    article_generator_context
+   article_generate_finalized  article_generator_finalized
+   article_generate_preread    article_generator_preread
+   pages_generate_context      page_generator_context
+   pages_generate_preread      page_generator_preread
+   pages_generator_finalized   page_generator_finalized
+   pages_generator_init        page_generator_init
+   static_generate_context     static_generator_context
+   static_generate_preread     static_generator_preread
+   ==========================  ===========================

docs/settings.rst

@@ -62,15 +62,16 @@ Setting name (default value)                                            What doe
                                                                         For example, if you would like to extract both the
                                                                         date and the slug, you could set something like:
                                                                         ``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``.
+                                                                        See :ref:`path_metadata`.
 `PATH_METADATA` (``''``)                                                Like ``FILENAME_METADATA``, but parsed from a page's
                                                                         full path relative to the content source directory.
+                                                                        See :ref:`path_metadata`.
+`EXTRA_PATH_METADATA` (``{}``)                                          Extra metadata dictionaries keyed by relative path.
+                                                                        See :ref:`path_metadata`.
 `DELETE_OUTPUT_DIRECTORY` (``False``)                                   Delete the output directory, and **all** of its contents, before
                                                                         generating new files. This can be useful in preventing older,
                                                                         unnecessary files from persisting in your output. However, **this is
                                                                         a destructive setting and should be handled with extreme care.**
-`FILES_TO_COPY` (``()``)                                                A list of files (or directories) to copy from the source (inside the
-                                                                        content directory) to the destination (inside the output directory).
-                                                                        For example: ``(('extra/robots.txt', 'robots.txt'),)``.
 `JINJA_EXTENSIONS` (``[]``)                                             A list of any Jinja2 extensions you want to use.
 `JINJA_FILTERS` (``{}``)                                                A list of custom Jinja2 filters you want to use.
                                                                         The dictionary should map the filtername to the filter function.
@@ -337,6 +338,52 @@ your resume, and a contact page — you could have::
                       'src/resume.html': 'dest/resume.html',
                       'src/contact.html': 'dest/contact.html'}
 
+
+.. _path_metadata:
+
+Path metadata
+=============
+
+Not all metadata needs to be `embedded in source file itself`__.  For
+example, blog posts are often named following a ``YYYY-MM-DD-SLUG.rst``
+pattern, or nested into ``YYYY/MM/DD-SLUG`` directories.  To extract
+metadata from the filename or path, set ``FILENAME_METADATA`` or
+``PATH_METADATA`` to regular expressions that use Python's `group name
+notation`_ ``(?P<name>…)``.  If you want to attach additional metadata
+but don't want to encode it in the path, you can set
+``EXTRA_PATH_METADATA``:
+
+.. parsed-literal::
+
+    EXTRA_PATH_METADATA = {
+        'relative/path/to/file-1': {
+            'key-1a': 'value-1a',
+            'key-1b': 'value-1b',
+            },
+        'relative/path/to/file-2': {
+            'key-2': 'value-2',
+            },
+        }
+
+This can be a convenient way to shift the installed location of a
+particular file:
+
+.. parsed-literal::
+
+    # Take advantage of the following defaults
+    # STATIC_SAVE_AS = '{path}'
+    # STATIC_URL = '{path}'
+    STATIC_PATHS = [
+        'extra/robots.txt',
+        ]
+    EXTRA_PATH_METADATA = {
+        'extra/robots.txt': {'path': 'robots.txt'},
+        }
+
+__ internal_metadata__
+.. _group name notation:
+   http://docs.python.org/3/library/re.html#regular-expression-syntax
+
 Feed settings
 =============