Apply fixes to taxonomy variable documentation

h/t @felixfontein Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Apr 14, 2017 · a868ef4 · a868ef4
1 parent 04d8c2f
commit a868ef4
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 23 deletions.
diff --git a/docs/template-variables.rst b/docs/template-variables.rst
@@ -189,37 +189,57 @@ Variable names enclosed in ``<>`` are dependent on the taxonomy.
 
 .. class:: table table-bordered table-striped
 
-==============  ==========================================  ===================
-Taxonomy        Variable                                    Value
-==============  ==========================================  ===================
-``archive``     ``overview_page_variable_name``             ``archive``
-``authors``     ``overview_page_variable_name``             ``authors``
-``categories``  ``overview_page_variable_name``             ``categories``
-``categories``  ``overview_page_items_variable_name``       ``cat_items``
-``categories``  ``overview_page_hierarchy_variable_name``   ``cat_hierarchy``
-``indexes``     ``overview_page_variable_name``             unavailable (None)
-``page_index``  ``overview_page_variable_name``             ``page_folder``
-``sections``    ``overview_page_variable_name``             ``sections``
-``tags``        ``overview_page_variable_name``             ``tags``
-``tags``        ``overview_page_items_variable_name``       ``items``
-==============  ==========================================  ===================
+======================  ==========================================  ===================
+Taxonomy                Variable                                    Value
+======================  ==========================================  ===================
+``archive``             ``overview_page_variable_name``             ``archive``
+``author``              ``overview_page_variable_name``             ``authors``
+``category``            ``overview_page_variable_name``             ``categories``
+``category``            ``overview_page_items_variable_name``       ``cat_items``
+``category``            ``overview_page_hierarchy_variable_name``   ``cat_hierarchy``
+``index``               ``overview_page_variable_name``             unavailable (None)
+``page_index_folder``   ``overview_page_variable_name``             ``page_folder``
+``section_index``       ``overview_page_variable_name``             ``sections``
+``tag``                 ``overview_page_variable_name``             ``tags``
+``tag``                 ``overview_page_items_variable_name``       ``items``
+======================  ==========================================  ===================
+
+Templates and settings used by taxonomies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: table table-bordered table-striped
+
+======================  ==================  ==================================  ======================================  ==============================================  ======================================  ==============================  ==============================
+Taxonomy                Has hierarchy       List (one classification) template  Index (one classification) template     Overview (list of classifications) template     Subcategories list template             List is an index                Show as list of subcategories
+======================  ==================  ==================================  ======================================  ==============================================  ======================================  ==============================  ==============================
+(default settings)      no                  tagindex.tmpl                       tagindex.tmpl                           list.tmpl                                       taxonomy_list.tmpl (does not exist)     no                              no
+``archive``             yes (0-3 levels)    list_post.tmpl                      archiveindex.tmpl                       list.tmpl                                       list.tmpl                               ``ARCHIVES_ARE_INDEXES``        ``not CREATE_FULL_ARCHIVES``
+``author``              no                  author.tmpl                         authorindex.tmpl                        authors.tmpl                                    n/a                                     ``AUTHOR_PAGES_ARE_INDEXES``    no
+``category``            yes                 tag.tmpl                            tagindex.tmpl                           tags.tmpl (with tags)                           n/a                                     ``CATEGORY_PAGES_ARE_INDEXES``  n/a
+``index``               no                  n/a                                 index.tmpl                              n/a                                             n/a                                     yes                             no
+``page_index_folder``   yes                 list.tmpl                           n/a                                     n/a                                             n/a                                     no                              no
+``section_index``       no                  list.tmpl                           sectionindex.tmpl                       n/a                                             n/a                                     ``POSTS_SECTIONS_ARE_INDEXES``  no
+``tag``                 no                  tag.tmpl                            tagindex.tmpl                           tags.tmpl (with categories)                     n/a                                     ``TAG_PAGES_ARE_INDEXES``       no
+======================  ==================  ==================================  ======================================  ==============================================  ======================================  ==============================  ==============================
 
 Classification overviews
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
+Hierarchy-related variables are available if and only if ``has_hierarchy`` is True.
+
 .. class:: table table-bordered table-striped
 
-==================================================================  ======  ============================================
+==================================================================  ======  ==============================================================================================================================================================================
 Name                                                                Type    Description
-==================================================================  ======  ============================================
+==================================================================  ======  ==============================================================================================================================================================================
 ``<overview_page_variable_name>``                                   str     List of classifications
-``<overview_page_items_variable_name>``                             str     List of items **(name, link)**
-``<overview_page_items_variable_name + "_with_postcount">``         str     List of items **(name, link, count)**
-``<overview_page_hierarchy_variable_name>``                         str?    List of hierarchies
-``<overview_page_hierarchy_variable_name + "_with_postcount">``     str     List of hierarchies, with added counts
+``<overview_page_items_variable_name>``                             list    List of items **(name, link)**
+``<overview_page_items_variable_name + "_with_postcount">``         list    List of items **(name, link, number of posts)**
+``<overview_page_hierarchy_variable_name>``                         list?   List of hierarchies **(name, full name, path, link, indent levels, indent to change before, indent to change after)**
+``<overview_page_hierarchy_variable_name + "_with_postcount">``     list?   List of hierarchies, with added counts **(name, full name, path, link, indent levels, indent to change before, indent to change after, number of children, number of posts)**
 ``has_hierarchy``                                                   bool    Value of ``has_hierarchy`` for the taxonomy
 ``permalink``                                                       str     Permanent link to page
-==================================================================  ======  ============================================
+==================================================================  ======  ==============================================================================================================================================================================
 
 Classification pages (lists)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -247,6 +267,29 @@ Name            Type    Description
 ``permalink``   str     Permanent link to page
 ==============  ======  =======================
 
+Hierarchical lists
+~~~~~~~~~~~~~~~~~~
+
+The indenting information can be used to render the items as a tree. The values have the following meanings:
+
+ * ``indent levels`` is a list of pairs ``(current_i, count_i)`` giving the current position (``0``, ..., ``count_i-1``) and maximum (``count_i``) in the hierarchy level ``i``;
+ * ``indent to change before`` is the difference of hierarchy levels between the previous and the current item; positive values indicate that the current item is indented further in and can be used to open HTML tags before the item;
+ * ``indent to change after`` is the difference of hierarchy levels between the current and the next item; negative values indicate that the current item is indented further in and can be used to close HTML tags after the item.
+
+Example:
+
+.. code:: text
+
+   +--- levels:[(0,3)], before:1, after:0
+   +-+- levels:[(1,3)], before:0, after:1
+   | +--- levels:[(1,3), (0,2)], before:1, after:0
+   | +-+- levels:[(1,3), (1,2)], before:0, after:1
+   |   +--- levels:[(1,3), (1,2), (0, 1)], before:1, after:-2
+   +-+- levels:[(2,3)], before:-2, after:1
+     +- levels:[(2,3), (0,1)], before:1, after:-2
+
+See ``tags.tmpl`` in the base themes for examples on how to render a tree as nested unordered lists in HTML.
+
 Variables available in archives
 -------------------------------
 
@@ -357,6 +400,8 @@ Name            Type    Description
 ``cat_items``   list    Categories *(name, full name, path, link, indent levels, indent to change before, indent to change after)*
 ==============  ======  ===========================================================================================================
 
+For more details about hierarchies, see `Hierarchical lists`_
+
 Variables available in shortcodes
 ---------------------------------
 

diff --git a/nikola/plugin_categories.py b/nikola/plugin_categories.py
@@ -560,7 +560,7 @@ class Taxonomy(BasePlugin):
         Whether to show the posts for one classification as an index or
         as a post list.
 
-    subcategories_list_template = "taxonomy_list":
+    subcategories_list_template = "taxonomy_list.tmpl":
         The template to use for the subcategories list when
         show_list_as_subcategories_list is True.
 
@@ -617,7 +617,7 @@ class Taxonomy(BasePlugin):
     include_posts_into_hierarchy_root = False
     show_list_as_subcategories_list = False
     show_list_as_index = False
-    subcategories_list_template = "taxonomy_list"
+    subcategories_list_template = "taxonomy_list.tmpl"
     generate_atom_feeds_for_post_lists = False
     template_for_single_list = "tagindex.tmpl"
     template_for_classification_overview = "list.tmpl"