From ffb671c61a24a9086343b54bad080e145ff33fc5 Mon Sep 17 00:00:00 2001
From: Dererk <dererk@satellogic.com>
Date: Tue, 15 Nov 2016 14:18:46 -0300
Subject: New upstream version 7.8.1

---
 docs/extending.txt | 174 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 156 insertions(+), 18 deletions(-)

(limited to 'docs/extending.txt')

diff --git a/docs/extending.txt b/docs/extending.txt
index 9e5dfbc..4fa935d 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -9,7 +9,7 @@
 Extending Nikola
 ================
 
-:Version: 7.7.3
+:Version: 7.8.1
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -63,13 +63,13 @@ When you run ``nikola --help`` you will see something like this:
     nikola import_feed          import a RSS/Atom dump
     nikola import_wordpress     import a WordPress dump
     nikola init                 create a Nikola site in the specified folder
-    nikola install_theme        install theme into current site
     nikola list                 list tasks from dodo file
     nikola mincss               apply mincss to the generated site
     nikola new_post             create a new blog post or site page
     nikola run                  run tasks
     nikola serve                start the test webserver
     nikola strace               use strace to list file_deps and targets
+    nikola theme                manage themes
     nikola version              print the Nikola version number
 
     nikola help                 show help / reference
@@ -172,8 +172,8 @@ TemplateSystem Plugins
 ----------------------
 
 Nikola supports Mako and Jinja2. If you prefer some other templating
-system, then you will have to write a TemplateSystem plugin. Here's how they work.
-First, you have to create a .plugin file. Here's the one for the Mako plugin:
+system, then you will have to write a ``TemplateSystem`` plugin. Here's how they work.
+First, you have to create a ``.plugin`` file. Here's the one for the Mako plugin:
 
 .. code-block:: ini
 
@@ -253,10 +253,10 @@ Task Plugins
 ------------
 
 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
+probably want to do a ``Task`` plugin, which will make it be part of the
+``nikola build`` command. These are the currently available tasks, all
 provided by plugins:
-T
+
 .. sidebar:: Other Tasks
 
     There are also ``LateTask`` plugins, which are executed later,
@@ -380,7 +380,7 @@ 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
+These plugins can also be used to extract metadata from a file. To do so, the
 plugin may implement ``read_metadata`` that will return a dict containing the
 metadata contained in the file.
 
@@ -389,7 +389,8 @@ RestExtension Plugins
 
 Implement directives for reStructuredText, see `media.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/media.py>`__ for a simple example.
 
-If your output depends on a config value, you need to make your post record a dependency on a pseudo-path, like this:
+If your output depends on a config value, you need to make your post record a
+dependency on a pseudo-path, like this:
 
 .. code-block:: text
 
@@ -397,17 +398,18 @@ If your output depends on a config value, you need to make your post record a de
 
 Then, whenever the ``OPTIONNAME`` option is changed in conf.py, the file will be rebuilt.
 
-If your directive depends or may depend on the whole timeline (like the post-list directive, where adding new posts
-to the site could make it stale), you should record a dependency on the
-pseudo-path ``####MAGIC####TIMELINE``.
+If your directive depends or may depend on the whole timeline (like the
+``post-list`` directive, where adding new posts to the site could make it
+stale), you should record a dependency on the pseudo-path
+``####MAGIC####TIMELINE``.
 
 MarkdownExtension Plugins
 -------------------------
 
 Implement Markdown extensions, see `mdx_nikola.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/markdown/mdx_nikola.py>`__ for a simple example.
 
-Note that python markdown extensions are often also available as separate packages. This is only meant to ship extensions
-along with Nikola.
+Note that Python markdown extensions are often also available as separate
+packages. This is only meant to ship extensions along with Nikola.
 
 SignalHandler Plugins
 ---------------------
@@ -445,6 +447,16 @@ Currently Nikola emits the following signals:
          'undeployed': # all files not deployed since they are either future posts/drafts
         }
 
+``compiled``
+    When a post/page is compiled from its source to html, before anything else is done with it.  The signal
+    data is in the form::
+
+        {
+         'source': # the path to the source file
+         'dest': # the path to the cache file for the post/page
+         'post': # the Post object for the post/page
+        }
+
 One example is the `deploy_hooks plugin. <https://github.com/getnikola/plugins/tree/master/v6/deploy_hooks>`__
 
 ConfigPlugin Plugins
@@ -458,7 +470,7 @@ from ``super()``. Example  plugin: `navstories <https://github.com/getnikola/plu
 PostScanner Plugins
 -------------------
 
-Get posts and stories from "somewhere" to be added to the timeline.
+Get posts and pages from "somewhere" to be added to the timeline.
 The only currently existing plugin of this kind reads them from disk.
 
 
@@ -477,7 +489,7 @@ Path/Link Resolution Mechanism
 
 Any plugin can register a function using ``Nikola.register_path_handler`` to
 allow resolution of paths and links. These are useful for templates, which
-can access them via _link.
+can access them via ``_link``.
 
 For example, you can always get a link to the path for the feed of the "foo" tag
 by using ``_link('tag_rss', 'foo')`` or the ``link://tag_rss/foo`` URL.
@@ -493,7 +505,7 @@ Here's the relevant code from the tag plugin.
     # path elements.
     def tag_rss_path(self, name, lang):
         return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
-                              self.site.config['TAG_PATH'], self.slugify_name(name) + ".xml"] if
+                              self.site.config['TAG_PATH'], self.slugify_name(name, lang) + ".xml"] if
                 _f]
 
 Template Hooks
@@ -529,7 +541,7 @@ HTML:
 
 
 The second argument to ``append()`` is used to determine whether the function
-needs access to the current template context and the site.  If it it set to
+needs access to the current template context and the site.  If it is set to
 ``True``, the function will also receive ``site`` and ``context`` keyword
 arguments.  Example use:
 
@@ -549,3 +561,129 @@ arguments.  Example use:
         endswith=endswith) + t
 
     site.template_hooks['page_header'].append(greeting, True, u'Nikola Tesla', endswith=u'!')
+
+Shortcodes
+==========
+
+Some (hopefully all) markup compilers support shortcodes in these forms::
+
+    {{% raw %}}{{% foo %}}  # No arguments
+    {{% foo bar %}}  # One argument, containing "bar"
+    {{% foo bar baz=bat %}}  # Two arguments, one containing "bar", one called "baz" containing "bat"
+
+    {{% foo %}}Some text{{% /foo %}}  # one argument called "data" containing "Some text"{{% /raw %}}
+
+So, if you are creating a plugin that generates markup, it may be a good idea
+to register it as a shortcode in addition of to restructured text directive or
+markdown extension, thus making it available to all markup formats.
+
+To implement your own shortcodes from a plugin, you can create a plugin inheriting ``ShortcodePlugin`` and 
+from its ``set_site`` method,  call
+
+``Nikola.register_shortcode(name, func)`` with the following arguments:
+
+``name``:
+    Name of the shortcode ("foo" in the examples above)
+``func``:
+    A function that will handle the shortcode
+
+The shortcode handler **must** return a two-element tuple, ``(output, dependencies)``
+
+``output``:
+    The text that will replace the shortcode in the document.
+
+``dependencies``:
+    A list of all the files on disk which will make the output be considered
+    out of date. For example, if the shortcode uses a template, it should be
+    the path to the template file.
+
+The shortcode handler **must** accept the following named arguments (or
+variable keyword arguments):
+
+``site``:
+    An instance of the Nikola class, to access site state
+
+``data``:
+    If the shortcut is used as opening/closing tags, it will be the text
+    between them, otherwise ``None``.
+
+``lang``:
+    The current language.    
+
+If the shortcode tag has arguments of the form ``foo=bar`` they will be
+passed as named arguments. Everything else will be passed as positional
+arguments in the function call.
+
+So, for example::
+
+    {{% raw %}}{{% foo bar baz=bat beep %}}Some text{{% /foo %}}{{% /raw %}}
+
+Assuming you registered ``foo_handler`` as the handler function for the
+shortcode named ``foo``, this will result in the following call when the above
+shortcode is encountered::
+
+    foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)
+
+Template-based Shortcodes
+-------------------------
+
+Another way to define a new shortcode is to add a template file to the
+``shortcodes`` directory of your site. The template file must have the
+shortcode name as the basename and the extension ``.tmpl``. For example, if you
+want to add a new shortcode named ``foo``, create the template file as
+``shortcodes/foo.tmpl``.
+
+When the shortcode is encountered, the matching template will be rendered with
+its context provided by the arguments given in the shortcode. Keyword arguments
+are passed directly, i.e. the key becomes the variable name in the template
+namespace with a matching string value. Non-keyword arguments are passed as
+string values in a tuple named ``_args``. As for normal shortcodes with a
+handler function, ``site`` and ``data`` will be added to the keyword arguments.
+
+Example:
+
+The following shortcode:
+
+.. code:: text
+
+    {{% raw %}}{{% foo bar="baz" spam %}}{{% /raw %}}
+
+With a template in ``shortcodes/foo.tmpl`` with this content (using Jinja2
+syntax in this example)
+
+.. code:: jinja
+
+    <div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div>
+
+Will result in this output
+
+.. code:: html
+
+    <div class="spam">baz</div>
+
+
+State and Cache
+===============
+
+Sometimes your plugins will need to cache things to speed up further actions. Here are the conventions for that:
+
+* If it's a file, put it somewhere in ``self.site.config['CACHE_FOLDER']`` (defaults to ``cache/``.
+* If it's a value, use ``self.site.cache.set(key, value)`` to set it and ``self.site.cache.get(key)`` to get it.
+  The key should be a string, the value should be json-encodable (so, be careful with datetime objects)
+
+The values and files you store there can **and will** be deleted sometimes by the user. They should always be
+things you can reconstruct without lossage. They are throwaways.
+
+On the other hand, sometimes you want to save something that is **not** a throwaway. These are things that may
+change the output, so the user should not delete them. We call that **state**. To save state:
+
+* If it's a file, put it somewhere in the working directory. Try not to do that please.
+* If it's a value, use ``self.site.state.set(key, value)`` to set it and ``self.state.cache.get(key)`` to get it.
+  The key should be a string, the value should be json-encodable (so, be careful with datetime objects)
+
+The ``cache`` and ``state`` objects are rather simplistic, and that's intentional. They have no default values: if
+the key is not there, you will get ``None`` and like it. They are meant to be both threadsafe, but hey, who can
+guarantee that sort of thing?
+
+There are no sections, and no access protection, so let's not use it to store passwords and such. Use responsibly.
+
-- 
cgit v1.2.3