[#847] Refactor a snippet from the theming docs

Also add snippets docstrings to best practices

ckanext/example_theme/v10_custom_snippet/templates/home/layout1.html

@@ -5,5 +5,6 @@
 {% endblock %}
 
 {% block featured_organization %}
-  {% snippet 'snippets/example_theme_most_popular_groups.html' %}
+  {% snippet 'snippets/example_theme_most_popular_groups.html',
+             groups=h.example_theme_most_popular_groups()  %}
 {% endblock %}

ckanext/example_theme/v10_custom_snippet/templates/snippets/example_theme_most_popular_groups.html

@@ -1,8 +1,13 @@
-{# Renders a list of the site's most popular groups. #}
+{#
 
+Renders a list of the site's most popular groups.
+
+groups - the list of groups to render
+
+#}
 <h3>Most popular groups</h3>
 <ul>
-  {% for group in h.example_theme_most_popular_groups() %}
+  {% for group in groups %}
     <li>
       <a href="{{ h.url_for('group_read', action='read', id=group.name) }}">
         <h3>{{ group.display_name }}</h3>

doc/theming/best-practices.rst

@@ -69,3 +69,15 @@ Always use CKAN's custom ``{% snippet %}`` tag instead of Jinja's default
 any variables explicitly passed to them by the calling template. They don't
 have access to the full context of the calling template, as included files do.
 This makes snippets more reusable, and much easier to debug.
+
+
+.. _snippet docstrings best practice:
+
+-------------------------------
+Snippets should have docstrings
+-------------------------------
+
+A snippet should have a docstring comment at the top of the file that briefly
+documents what the snippet does and what parameters it requires. For example:
+
+.. literalinclude:: /../ckanext/example_theme/v10_custom_snippet/templates/snippets/example_theme_most_popular_groups.html

doc/theming/templates.rst

@@ -564,16 +564,22 @@ The snippets will be callable from other templates immediately.
    added your plugin's custom template directory to CKAN, see :ref:`template
    overriding`.
 
-Let's create a custom snippet to display our most popular groups, and put the
-``<h3>Most popular groups</h3>`` heading and the code to call the helper
-function to retrieve the groups into the snippet, so that we can reuse the
-whole thing on different parts of the site if we want to.
+Let's create a custom snippet to display our most popular groups, we'll put
+the ``<h3>Most popular groups</h3>`` heading into the snippet and make it nice
+and modular, so that we can reuse the whole thing on different parts of the
+site if we want to.
 
 Create a new directory |snippets_dir| containing a file named
 ``example_theme_most_popular_groups.html`` with these contents:
 
 .. literalinclude:: /../ckanext/example_theme/v10_custom_snippet/templates/snippets/example_theme_most_popular_groups.html
 
+.. note::
+
+   As in the example above, a snippet should have a docstring at the top of the
+   file that briefly documents what the snippet does and what parameters it
+   requires. See :ref:`snippet docstrings best practice`.
+
 This code uses a Jinja2 ``for`` loop to render each of the groups, and calls a
 number of CKAN's template helper functions: