Merge tag 'upstream/7.6.0'

Upstream version 7.6.0

1 files changed, 50 insertions, 20 deletions

diff --git a/docs/extending.txt b/docs/extending.txt
index bb337f7..9db5344 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 7.1.0
+:Version: 7.6.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -38,7 +38,7 @@ When you run ``nikola --help`` you will see something like this::
 
     $ nikola help
     Nikola is a tool to create static websites and blogs. For full documentation and more
-    information, please visit http://getnikola.com
+    information, please visit https://getnikola.com/
 
 
     Available commands:
@@ -87,7 +87,7 @@ First, the ``serve.plugin`` file:
     [Documentation]
     Author = Roberto Alsina
     Version = 0.1
-    Website = http://getnikola.com
+    Website = https://getnikola.com
     Description = Start test server.
 
 .. note:: If you want to publish your plugin on the Plugin Index, `read
@@ -179,7 +179,7 @@ First, you have to create a .plugin file. Here's the one for the Mako plugin:
     [Documentation]
     Author = Roberto Alsina
     Version = 0.1
-    Website = http://getnikola.com
+    Website = https://getnikola.com
     Description = Support for Mako templates.
 
 .. note:: If you want to publish your plugin on the Plugin Index, `read
@@ -205,31 +205,41 @@ a stub for a hypothetical system called "Templater":
         # name has to match Name in the .plugin file
         name = "templater"
 
+        # A list of directories where the templates will be
+        # located. Most template systems have some sort of
+        # template loading tool that can use this.
+        def set_directories(self, directories, cache_folder):
+            """Sets the list of folders where templates are located and cache."""
+            pass
+
         # You *must* implement this, even if to return []
         # It should return a list of all the files that,
         # when changed, may affect the template's output.
         # usually this involves template inheritance and
         # inclusion.
-        def get_deps(self, filename):
+        def template_deps(self, template_name):
+            """Returns filenames which are dependencies for a template."""
             return []
 
-        # A list of directories where the templates will be
-        # located. Most template systems have some sort of
-        # template loading tool that can use this.
+        def render_template(self, template_name, output_name, context):
+            """Renders template to a file using context.
 
-        def set_directories(self, directories):
-            """Create a template lookup."""
+            This must save the data to output_name *and* return it
+            so that the caller may do additional processing.
+            """
             pass
 
         # The method that does the actual rendering.
         # template_name is the name of the template file,
-        # output_name is the file for the output, context
-        # is a dictionary containing the data the template
+        # context is a dictionary containing the data the template
         # uses for rendering.
+        def render_template_to_string(self, template, context):
+            """Renders template to a string using context. """
+            pass
 
-        def render_template(self, template_name, output_name,
-            context, global_context):
-            """Render the template into output_name using context."""
+        def inject_directory(self, directory):
+            """Injects the directory with the lowest priority in the
+            template search mechanism."""
             pass
 
 
@@ -240,7 +250,7 @@ If you want to do something that depends on the data in your site, you
 probably want to do a Task plugin, which will make it be part of the
 ``nikola build`` command. There are the currently available tasks, all
 provided by plugins:
-
+T
 .. sidebar:: Other Tasks
 
     There are also ``LateTask`` plugins, which are executed later,
@@ -290,7 +300,7 @@ in the logical ways:
     [Documentation]
     Author = Roberto Alsina
     Version = 0.1
-    Website = http://getnikola.com
+    Website = https://getnikola.com
     Description = Copy theme assets into output.
 
 
@@ -364,6 +374,10 @@ They must provide:
 If the compiler produces something other than HTML files, it should also implement ``extension`` which
 returns the preferred extension for the output file.
 
+These plugins can also be used to extract metadata from file. To do so, the
+plugin may implement ``read_metadata`` that will return a dict containing the
+metadata contained in the file.
+
 RestExtension Plugins
 ---------------------
 
@@ -393,9 +407,11 @@ Currently Nikola emits the following signals:
     When all the configuration file is processed. Note that plugins are activated before this is emitted.
 ``scanned``
     After posts are scanned.
-``new_post``
-    When a new post is created, using the ``nikola new_post`` command.  The signal
+``new_post`` / ``new_page``
+    When a new post is created, using the ``nikola new_post``/``nikola new_page`` commands.  The signal
     data contains the path of the file, and the metadata file (if there is one).
+``existing_post`` / ``existing_page``
+    When a new post fails to be created due to a title conflict. Contains the same data as ``new_post``.
 ``deployed``
     When the ``nikola deploy`` command is run, and there is at least one new
     entry/post since ``last_deploy``.  The signal data is of the form::
@@ -408,11 +424,25 @@ Currently Nikola emits the following signals:
          'undeployed': # all files not deployed since they are either future posts/drafts
         }
 
+ConfigPlugin Plugins
+--------------------
+
+Does nothing specific, can be used to modify the site object (and thus the config).
+
+Put all the magic you want in ``set_site()``, and don’t forget to run the one
+from ``super()``.
+
+PostScanner Plugins
+-------------------
+
+Get posts and stories from "somewhere" to be added to the timeline.
+The only currently existing plugin of this kind reads them from disk.
+
 
 Plugin Index
 ============
 
-There is a `plugin index <http://plugins.getnikola.com/>`__, which stores all
+There is a `plugin index <https://plugins.getnikola.com/>`__, which stores all
 of the plugins for Nikola people wanted to share with the world.
 
 You may want to read the `README for the Index