Adds new Understanding Jinja topic, and fixes several Jinja doc issues.

Removes the "Full list of builtin ..." from each module reference list, leaving just the module type for scanability.

Refs #12470
Refs #10206
Refs #10480
Refs #23522
Refs #33023

doc/ref/auth/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.auth:
 
-=================================
-Full list of builtin auth modules
-=================================
+============
+auth modules
+============
 
 .. currentmodule:: salt.auth
 

doc/ref/beacons/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.beacons:
 
-===================================
-Full list of builtin beacon modules
-===================================
+==============
+beacon modules
+==============
 
 .. currentmodule:: salt.beacons
 

doc/ref/engines/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.engines:
 
-===================================
-Full list of builtin engine modules
-===================================
+==============
+engine modules
+==============
 
 .. currentmodule:: salt.engines
 

doc/ref/file_server/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.fileserver:
 
-=======================================
-Full list of builtin fileserver modules
-=======================================
+==================
+fileserver modules
+==================
 
 .. currentmodule:: salt.fileserver
 

doc/ref/grains/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.grains:
 
-===================================
-Full list of builtin grains modules
-===================================
+==============
+grains modules
+==============
 
 .. currentmodule:: salt.grains
 

doc/ref/modules/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt_modules:
 
-======================================
-Full list of builtin execution modules
-======================================
+=================
+execution modules
+=================
 
 .. admonition:: Virtual modules
 

doc/ref/netapi/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-netapi-modules:
 
-===========================
-Full list of netapi modules
-===========================
+==============
+netapi modules
+==============
 
 .. toctree::
     :maxdepth: 2

doc/ref/output/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.output:
 
-===================================
-Full list of builtin output modules
-===================================
+==============
+output modules
+==============
 
 Follow one of the below links for further information and examples
 

doc/ref/pillar/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.pillars:
 
-===================================
-Full list of builtin pillar modules
-===================================
+==============
+pillar modules
+==============
 
 .. currentmodule:: salt.pillar
 

doc/ref/proxy/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.proxy:
 
-==================================
-Full list of builtin proxy modules
-==================================
+=============
+proxy modules
+=============
 
 .. currentmodule:: salt.proxy
 

doc/ref/queues/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.queues:
 
-===========================
-Full list of builtin queues
-===========================
+=============
+queue modules
+=============
 
 .. currentmodule:: salt.queues
 

doc/ref/renderers/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.renderers:
 
-=====================================
-Full list of builtin renderer modules
-=====================================
+================
+renderer modules
+================
 
 .. currentmodule:: salt.renderers
 

doc/ref/returners/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.returners:
 
-=====================================
-Full list of builtin returner modules
-=====================================
+================
+returner modules
+================
 
 .. currentmodule:: salt.returners
 

doc/ref/roster/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.roster:
 
-===================================
-Full list of builtin roster modules
-===================================
+==============
+roster modules
+==============
 
 .. currentmodule:: salt.roster
 

doc/ref/runners/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.runners:
 
-===========================
-Full list of runner modules
-===========================
+==============
+runner modules
+==============
 
 .. currentmodule:: salt.runners
 

doc/ref/sdb/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.sdb:
 
-================================
-Full list of builtin sdb modules
-================================
+===========
+sdb modules
+===========
 
 .. currentmodule:: salt.sdb
 

doc/ref/serializers/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.serializers:
 
-================================
-Full list of builtin serializers
-================================
+==================
+serializer modules
+==================
 
 .. currentmodule:: salt.serializers
 

doc/ref/states/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.states:
 
-==================================
-Full list of builtin state modules
-==================================
+=============
+state modules
+=============
 
 .. currentmodule:: salt.states
 

doc/ref/thorium/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.thorium:
 
-====================================
-Full list of builtin thorium modules
-====================================
+===============
+thorium modules
+===============
 
 .. currentmodule:: salt.thorium
 

doc/ref/tops/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.tops:
 
-========================================
-Full list of builtin master tops modules
-========================================
+===================
+master tops modules
+===================
 
 .. currentmodule:: salt.tops
 

doc/ref/wheel/all/index.rst

@@ -1,8 +1,8 @@
 .. _all-salt.wheel:
 
-==================================
-Full list of builtin wheel modules
-==================================
+=============
+wheel modules
+=============
 
 .. currentmodule:: salt.wheel
 

doc/topics/jinja/index.rst

@@ -0,0 +1,364 @@
+.. _jinja:
+
+===================
+Understanding Jinja
+===================
+
+`Jinja <http://jinja.pocoo.org/docs/>`_ is the default templating language
+in SLS files.
+
+Jinja in States
+===============
+
+.. _Jinja: http://jinja.pocoo.org/docs/templates/
+
+Jinja is evaluated before YAML, which means it is evaluated before the States
+are run.
+
+The most basic usage of Jinja in state files is using control structures to
+wrap conditional or redundant state elements:
+
+.. code-block:: yaml
+
+    {% if grains['os'] != 'FreeBSD' %}
+    tcsh:
+        pkg:
+            - installed
+    {% endif %}
+
+    motd:
+      file.managed:
+        {% if grains['os'] == 'FreeBSD' %}
+        - name: /etc/motd
+        {% elif grains['os'] == 'Debian' %}
+        - name: /etc/motd.tail
+        {% endif %}
+        - source: salt://motd
+
+In this example, the first if block will only be evaluated on minions that
+aren't running FreeBSD, and the second block changes the file name based on the
+*os* grain.
+
+Writing **if-else** blocks can lead to very redundant state files however. In
+this case, using :doc:`pillars</topics/pillar/index>`, or using a previously
+defined variable might be easier:
+
+.. code-block:: yaml
+
+    {% set motd = ['/etc/motd'] %}
+    {% if grains['os'] == 'Debian' %}
+      {% set motd = ['/etc/motd.tail', '/var/run/motd'] %}
+    {% endif %}
+
+    {% for motdfile in motd %}
+    {{ motdfile }}:
+      file.managed:
+        - source: salt://motd
+    {% endfor %}
+
+Using a variable set by the template, the `for loop`_ will iterate over the
+list of MOTD files to update, adding a state block for each file.
+
+The filter_by function can also be used to set variables based on grains:
+
+.. code-block:: yaml
+
+   {% set auditd = salt['grains.filter_by']({
+   'RedHat': { 'package': 'audit' },
+   'Debian': { 'package': 'auditd' },
+   }) %}
+
+.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for
+
+Include and Import
+==================
+
+Includes and imports_ can be used to share common, reusable state configuration
+between state files and between files.
+
+.. code-block:: yaml
+
+    {% from 'lib.sls' import test %}
+
+This would import the ``test`` template variable or macro, not the ``test``
+state element, from the file ``lib.sls``. In the case that the included file
+performs checks again grains, or something else that requires context, passing
+the context into the included file is required:
+
+.. code-block:: yaml
+
+    {% from 'lib.sls' import test with context %}
+
+Including Context During Include/Import
+---------------------------------------
+
+By adding ``with context`` to the include/import directive, the
+current context can be passed to an included/imported template.
+
+.. code-block:: yaml
+
+    {% import 'openssl/vars.sls' as ssl with context %}
+
+
+.. _imports: http://jinja.pocoo.org/docs/templates/#import
+
+Macros
+======
+
+Macros_ are helpful for eliminating redundant code. Macros are most useful as
+mini-templates to repeat blocks of strings with a few parameterized variables.
+Be aware that stripping whitespace from the template block, as well as
+contained blocks, may be necessary to emulate a variable return from the macro.
+
+.. code-block:: yaml
+
+    # init.sls
+    {% from 'lib.sls' import pythonpkg with context %}
+
+    python-virtualenv:
+      pkg.installed:
+        - name: {{ pythonpkg('virtualenv') }}
+
+    python-fabric:
+      pkg.installed:
+        - name: {{ pythonpkg('fabric') }}
+
+.. code-block:: yaml
+
+    # lib.sls
+    {% macro pythonpkg(pkg) -%}
+      {%- if grains['os'] == 'FreeBSD' -%}
+        py27-{{ pkg }}
+      {%- elif grains['os'] == 'Debian' -%}
+        python-{{ pkg }}
+      {%- endif -%}
+    {%- endmacro %}
+
+This would define a macro_ that would return a string of the full package name,
+depending on the packaging system's naming convention. The whitespace of the
+macro was eliminated, so that the macro would return a string without line
+breaks, using `whitespace control`_.
+
+Template Inheritance
+====================
+
+`Template inheritance`_ works fine from state files and files. The search path
+starts at the root of the state tree or pillar.
+
+.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance
+.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros
+.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros
+.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control
+
+Filters
+=======
+
+Saltstack extends `builtin filters`_ with these custom filters:
+
+strftime
+  Converts any time related object into a time based string. It requires a
+  valid :ref:`strftime directives <python2:strftime-strptime-behavior>`. An
+  :ref:`exhaustive list <python2:strftime-strptime-behavior>` can be found in
+  the official Python documentation.
+
+  .. code-block:: yaml
+
+      {% set curtime = None | strftime() %}
+
+  Fuzzy dates require the `timelib`_ Python module is installed.
+
+  .. code-block:: yaml
+
+      {{ "2002/12/25"|strftime("%y") }}
+      {{ "1040814000"|strftime("%Y-%m-%d") }}
+      {{ datetime|strftime("%u") }}
+      {{ "tomorrow"|strftime }}
+
+sequence
+  Ensure that parsed data is a sequence.
+
+yaml_encode
+  Serializes a single object into a YAML scalar with any necessary
+  handling for escaping special characters.  This will work for any
+  scalar YAML data type: ints, floats, timestamps, booleans, strings,
+  unicode.  It will *not* work for multi-objects such as sequences or
+  maps.
+
+  .. code-block:: yaml
+
+      {%- set bar = 7 %}
+      {%- set baz = none %}
+      {%- set zip = true %}
+      {%- set zap = 'The word of the day is "salty"' %}
+
+      {%- load_yaml as foo %}
+      bar: {{ bar|yaml_encode }}
+      baz: {{ baz|yaml_encode }}
+      baz: {{ zip|yaml_encode }}
+      baz: {{ zap|yaml_encode }}
+      {%- endload %}
+
+  In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
+  identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
+  identical.
+
+yaml_dquote
+  Serializes a string into a properly-escaped YAML double-quoted
+  string.  This is useful when the contents of a string are unknown
+  and may contain quotes or unicode that needs to be preserved.  The
+  resulting string will be emitted with opening and closing double
+  quotes.
+
+  .. code-block:: yaml
+
+      {%- set bar = '"The quick brown fox . . ."' %}
+      {%- set baz = 'The word of the day is "salty".' %}
+
+      {%- load_yaml as foo %}
+      bar: {{ bar|yaml_dquote }}
+      baz: {{ baz|yaml_dquote }}
+      {%- endload %}
+
+  In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
+  identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
+  identical.  If variable contents are not guaranteed to be a string
+  then it is better to use ``yaml_encode`` which handles all YAML
+  scalar types.
+
+yaml_squote
+   Similar to the ``yaml_dquote`` filter but with single quotes.  Note
+   that YAML only allows special escapes inside double quotes so
+   ``yaml_squote`` is not nearly as useful (viz. you likely want to
+   use ``yaml_encode`` or ``yaml_dquote``).
+
+.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters
+.. _`timelib`: https://github.com/pediapress/timelib/
+
+Jinja in Files
+==============
+
+Jinja_ can be used in the same way in managed files:
+
+.. code-block:: yaml
+
+    # redis.sls
+    /etc/redis/redis.conf:
+        file.managed:
+            - source: salt://redis.conf
+            - template: jinja
+            - context:
+                bind: 127.0.0.1
+
+.. code-block:: yaml
+
+    # lib.sls
+    {% set port = 6379 %}
+
+.. code-block:: ini
+
+    # redis.conf
+    {% from 'lib.sls' import port with context %}
+    port {{ port }}
+    bind {{ bind }}
+
+As an example, configuration was pulled from the file context and from an
+external template file.
+
+.. note::
+
+    Macros and variables can be shared across templates. They should not be
+    starting with one or more underscores, and should be managed by one of the
+    following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and
+    `import_json`.
+
+Escaping Jinja
+==============
+
+Occasionally, it may be necessary to escape Jinja syntax. There are two ways to
+to do this in Jinja. One is escaping individual variables or strings and the
+other is to escape entire blocks.
+
+To escape a string commonly used in Jinja syntax such as ``{{``, you can use the
+following syntax:
+
+.. code-block:: jinja
+
+    {{ '{{' }}
+
+For larger blocks that contain Jinja syntax that needs to be escaped, you can use
+raw blocks:
+
+.. code-block:: jinja
+
+    {% raw %}
+        some text that contains jinja characters that need to be escaped
+    {% endraw %}
+
+See the `Escaping`_ section of Jinja's documentation to learn more.
+
+A real-word example of needing to use raw tags to escape a larger block of code
+is when using ``file.managed`` with the ``contents_pillar`` option to manage
+files that contain something like consul-template, which shares a syntax subset
+with Jinja. Raw blocks are necessary here because the Jinja in the pillar would
+be rendered before the file.managed is ever called, so the Jinja syntax must be
+escaped:
+
+.. code-block:: jinja
+
+    {% raw %}
+    - contents_pillar: |
+        job "example-job" {
+          <snipped>
+          task "example" {
+              driver = "docker"
+
+              config {
+                  image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}"
+          <snipped>
+    {% endraw %}
+
+.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping
+
+Calling Salt Functions
+======================
+
+The Jinja renderer provides a shorthand lookup syntax for the ``salt``
+dictionary of :term:`execution function <Execution Function>`.
+
+.. versionadded:: 2014.7.0
+
+.. code-block:: yaml
+
+    # The following two function calls are equivalent.
+    {{ salt['cmd.run']('whoami') }}
+    {{ salt.cmd.run('whoami') }}
+
+Debugging
+=========
+
+The ``show_full_context`` function can be used to output all variables present
+in the current Jinja context.
+
+.. versionadded:: 2014.7.0
+
+.. code-block:: yaml
+
+    Context is: {{ show_full_context() }}
+
+Custom Execution Modules
+========================
+
+Custom execution modules can be used to supplement or replace complex Jinja. Many
+tasks that require complex looping and logic are trivial when using Python
+in a Salt execution module. Salt execution modules are easy to write and
+distribute to Salt minions.
+
+:ref:`Writing Execution Modules <writing-execution-modules>`
+
+Functions in custom execution modules are available in the Salt execution
+module dictionary just like the built-in execution modules:
+
+.. code-block:: yaml
+
+    {{ salt['my_custom_module.my_custom_function']() }}
+

doc/topics/targeting/nodegroups.rst

@@ -52,7 +52,7 @@ To match a nodegroup on the CLI, use the ``-N`` command-line option:
 
 .. note::
 
-    The ``N@`` classifier cannot be used in compound mathes within the CLI or
+    The ``N@`` classifier cannot be used in compound matches within the CLI or
     :term:`top file`, it is only recognized in the :conf_master:`nodegroups`
     master config file parameter.
 

doc/topics/tutorials/pillar.rst

@@ -324,11 +324,14 @@ specified list, notice the nested pillar dict:
 
     salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
 
+This will attempt to install telnet on your minions, feel free to
+uninstall the package or replace telnet value with anything else.
+
 .. note::
-
-    This will attempt to install telnet on your minions, feel free to
-    uninstall the package or replace telnet value with anything else.
-
+   Be aware that when sending sensitive data via pillar on the command-line
+   that the publication containing that data will be received by all minions
+   and will not be restricted to the targeted minions. This may represent
+   a security concern in some cases.
 
 More On Pillar
 ==============

doc/topics/using_salt.rst

@@ -14,6 +14,7 @@ This section describes the fundamental components and concepts that you need to
     ../ref/runners/index
     engines/index
     yaml/index
+    jinja/index
     troubleshooting/index
     ../faq
     best_practices

doc/topics/yaml/index.rst

@@ -1,3 +1,6 @@
+.. _yaml:
+
+==================
 Understanding YAML
 ==================
 
@@ -107,4 +110,10 @@ Learning More
 One easy way to learn more about how YAML gets rendered into Python data structures is
 to use an online YAML parser to see the Python output.
 
-One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/
+One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/
+
+Templating
+----------
+Jinja statements and expressions are allowed by default in SLS files. See
+:ref:`Understanding Jinja <jinja>`.
+

salt/netapi/rest_cherrypy/app.py

@@ -247,6 +247,22 @@ command sent to minions as well as a runner function on the master::
 .. |200| replace:: success
 .. |401| replace:: authentication required
 .. |406| replace:: requested Content-Type not available
+
+A Note About Curl
+=================
+
+When sending passwords and data that might need to be urlencoded, you must set
+the ``-d`` flag to indicate the content type, and the ``--data-urlencode`` flag
+to urlencode the input.
+
+.. code-block:: bash
+
+    curl -ksi http://localhost:8000/login \\
+    -H "Accept: application/json" \\
+    -d username='myapiuser' \\
+    --data-urlencode password='1234+' \\
+    -d eauth='pam'
+
 '''
 # We need a custom pylintrc here...
 # pylint: disable=W0212,E1101,C0103,R0201,W0221,W0613

salt/renderers/jinja.py

@@ -2,319 +2,7 @@
 '''
 Jinja loading utils to enable a more powerful backend for jinja templates
 
-Jinja in States
-===============
-
-.. _Jinja: http://jinja.pocoo.org/docs/templates/
-
-The most basic usage of Jinja in state files is using control structures to
-wrap conditional or redundant state elements:
-
-.. code-block:: yaml
-
-    {% if grains['os'] != 'FreeBSD' %}
-    tcsh:
-        pkg:
-            - installed
-    {% endif %}
-
-    motd:
-      file.managed:
-        {% if grains['os'] == 'FreeBSD' %}
-        - name: /etc/motd
-        {% elif grains['os'] == 'Debian' %}
-        - name: /etc/motd.tail
-        {% endif %}
-        - source: salt://motd
-
-In this example, the first if block will only be evaluated on minions that
-aren't running FreeBSD, and the second block changes the file name based on the
-*os* grain.
-
-Writing **if-else** blocks can lead to very redundant state files however. In
-this case, using :doc:`pillars</topics/pillar/index>`, or using a previously
-defined variable might be easier:
-
-.. code-block:: yaml
-
-    {% set motd = ['/etc/motd'] %}
-    {% if grains['os'] == 'Debian' %}
-      {% set motd = ['/etc/motd.tail', '/var/run/motd'] %}
-    {% endif %}
-
-    {% for motdfile in motd %}
-    {{ motdfile }}:
-      file.managed:
-        - source: salt://motd
-    {% endfor %}
-
-Using a variable set by the template, the `for loop`_ will iterate over the
-list of MOTD files to update, adding a state block for each file.
-
-.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for
-
-Include and Import
-==================
-
-Includes and imports_ can be used to share common, reusable state configuration
-between state files and between files.
-
-.. code-block:: yaml
-
-    {% from 'lib.sls' import test %}
-
-This would import the ``test`` template variable or macro, not the ``test``
-state element, from the file ``lib.sls``. In the case that the included file
-performs checks again grains, or something else that requires context, passing
-the context into the included file is required:
-
-.. code-block:: yaml
-
-    {% from 'lib.sls' import test with context %}
-
-.. _imports: http://jinja.pocoo.org/docs/templates/#import
-
-Macros
-======
-
-Macros_ are helpful for eliminating redundant code, however stripping whitespace
-from the template block, as well as contained blocks, may be necessary to
-emulate a variable return from the macro.
-
-.. code-block:: yaml
-
-    # init.sls
-    {% from 'lib.sls' import pythonpkg with context %}
-
-    python-virtualenv:
-      pkg.installed:
-        - name: {{ pythonpkg('virtualenv') }}
-
-    python-fabric:
-      pkg.installed:
-        - name: {{ pythonpkg('fabric') }}
-
-.. code-block:: yaml
-
-    # lib.sls
-    {% macro pythonpkg(pkg) -%}
-      {%- if grains['os'] == 'FreeBSD' -%}
-        py27-{{ pkg }}
-      {%- elif grains['os'] == 'Debian' -%}
-        python-{{ pkg }}
-      {%- endif -%}
-    {%- endmacro %}
-
-This would define a macro_ that would return a string of the full package name,
-depending on the packaging system's naming convention. The whitespace of the
-macro was eliminated, so that the macro would return a string without line
-breaks, using `whitespace control`_.
-
-Template Inheritance
-====================
-
-`Template inheritance`_ works fine from state files and files. The search path
-starts at the root of the state tree or pillar.
-
-.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance
-.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros
-.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros
-.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control
-
-Filters
-=======
-
-Saltstack extends `builtin filters`_ with these custom filters:
-
-strftime
-  Converts any time related object into a time based string. It requires a
-  valid :ref:`strftime directives <python2:strftime-strptime-behavior>`. An
-  :ref:`exhaustive list <python2:strftime-strptime-behavior>` can be found in
-  the official Python documentation.
-
-  .. code-block:: yaml
-
-      {% set curtime = None | strftime() %}
-
-  Fuzzy dates require the `timelib`_ Python module is installed.
-
-  .. code-block:: yaml
-
-      {{ "2002/12/25"|strftime("%y") }}
-      {{ "1040814000"|strftime("%Y-%m-%d") }}
-      {{ datetime|strftime("%u") }}
-      {{ "tomorrow"|strftime }}
-
-sequence
-  Ensure that parsed data is a sequence.
-
-yaml_encode
-  Serializes a single object into a YAML scalar with any necessary
-  handling for escaping special characters.  This will work for any
-  scalar YAML data type: ints, floats, timestamps, booleans, strings,
-  unicode.  It will *not* work for multi-objects such as sequences or
-  maps.
-
-  .. code-block:: yaml
-
-      {%- set bar = 7 %}
-      {%- set baz = none %}
-      {%- set zip = true %}
-      {%- set zap = 'The word of the day is "salty"' %}
-
-      {%- load_yaml as foo %}
-      bar: {{ bar|yaml_encode }}
-      baz: {{ baz|yaml_encode }}
-      baz: {{ zip|yaml_encode }}
-      baz: {{ zap|yaml_encode }}
-      {%- endload %}
-
-  In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
-  identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
-  identical.
-
-yaml_dquote
-  Serializes a string into a properly-escaped YAML double-quoted
-  string.  This is useful when the contents of a string are unknown
-  and may contain quotes or unicode that needs to be preserved.  The
-  resulting string will be emitted with opening and closing double
-  quotes.
-
-  .. code-block:: yaml
-
-      {%- set bar = '"The quick brown fox . . ."' %}
-      {%- set baz = 'The word of the day is "salty".' %}
-
-      {%- load_yaml as foo %}
-      bar: {{ bar|yaml_dquote }}
-      baz: {{ baz|yaml_dquote }}
-      {%- endload %}
-
-  In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
-  identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
-  identical.  If variable contents are not guaranteed to be a string
-  then it is better to use ``yaml_encode`` which handles all YAML
-  scalar types.
-
-yaml_squote
-   Similar to the ``yaml_dquote`` filter but with single quotes.  Note
-   that YAML only allows special escapes inside double quotes so
-   ``yaml_squote`` is not nearly as useful (viz. you likely want to
-   use ``yaml_encode`` or ``yaml_dquote``).
-
-.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters
-.. _`timelib`: https://github.com/pediapress/timelib/
-
-Jinja in Files
-==============
-
-Jinja_ can be used in the same way in managed files:
-
-.. code-block:: yaml
-
-    # redis.sls
-    /etc/redis/redis.conf:
-        file.managed:
-            - source: salt://redis.conf
-            - template: jinja
-            - context:
-                bind: 127.0.0.1
-
-.. code-block:: yaml
-
-    # lib.sls
-    {% set port = 6379 %}
-
-.. code-block:: ini
-
-    # redis.conf
-    {% from 'lib.sls' import port with context %}
-    port {{ port }}
-    bind {{ bind }}
-
-As an example, configuration was pulled from the file context and from an
-external template file.
-
-.. note::
-
-    Macros and variables can be shared across templates. They should not be
-    starting with one or more underscores, and should be managed by one of the
-    following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and
-    `import_json`.
-
-Escaping Jinja
-==============
-
-Occasionally, it may be necessary to escape Jinja syntax. There are two ways to
-to do this in Jinja. One is escaping individual variables or strings and the
-other is to escape entire blocks.
-
-To escape a string commonly used in Jinja syntax such as ``{{``, you can use the
-following syntax:
-
-.. code-block:: jinja
-
-    {{ '{{' }}
-
-For larger blocks that contain Jinja syntax that needs to be escaped, you can use
-raw blocks:
-
-.. code-block:: jinja
-
-    {% raw %]
-        some text that contains jinja characters that need to be escaped
-    {% endraw %}
-
-See the `Escaping`_ section of Jinja's documentation to learn more.
-
-A real-word example of needing to use raw tags to escape a larger block of code
-is when using ``file.managed`` with the ``contents_pillar`` option to manage
-files that contain something like consul-template, which shares a syntax subset
-with Jinja. Raw blocks are necessary here because the Jinja in the pillar would
-be rendered before the file.managed is ever called, so the Jinja syntax must be
-escaped:
-
-.. code-block:: jinja
-
-    {% raw %}
-    - contents_pillar: |
-        job "example-job" {
-          <snipped>
-          task "example" {
-              driver = "docker"
-
-              config {
-                  image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}"
-          <snipped>
-    {% endraw %}
-
-.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping
-
-Calling Salt Functions
-======================
-
-The Jinja renderer provides a shorthand lookup syntax for the ``salt``
-dictionary of :term:`execution function <Execution Function>`.
-
-.. versionadded:: 2014.7.0
-
-.. code-block:: yaml
-
-    # The following two function calls are equivalent.
-    {{ salt['cmd.run']('whoami') }}
-    {{ salt.cmd.run('whoami') }}
-
-Debugging
-=========
-
-The ``show_full_context`` function can be used to output all variables present
-in the current Jinja context.
-
-.. versionadded:: 2014.7.0
-
-.. code-block:: yaml
-
-    Context is: {{ show_full_context() }}
+For Jinja usage information see :ref:`Understanding Jinja <jinja>`.
 '''
 
 # Import python libs

salt/renderers/yaml.py

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 '''
 YAML Renderer for Salt
+
+For YAML usage information see :ref:`Understanding YAML <yaml>`.
 '''
 
 from __future__ import absolute_import