From a868ef4f3d9ece66e03685fa3e5eb3cfa1c4420f Mon Sep 17 00:00:00 2001 From: Chris Warrick Date: Fri, 14 Apr 2017 12:27:55 +0200 Subject: [PATCH] Apply fixes to taxonomy variable documentation h/t @felixfontein Signed-off-by: Chris Warrick --- docs/template-variables.rst | 87 ++++++++++++++++++++++++++++--------- nikola/plugin_categories.py | 4 +- 2 files changed, 68 insertions(+), 23 deletions(-) diff --git a/docs/template-variables.rst b/docs/template-variables.rst index 50c9fba314..571c2ba9d8 100644 --- 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 -================================================================== ====== ============================================ +================================================================== ====== ============================================================================================================================================================================== ```` str List of classifications -```` str List of items **(name, link)** -```` str List of items **(name, link, count)** -```` str? List of hierarchies -```` str List of hierarchies, with added counts +```` list List of items **(name, link)** +```` list List of items **(name, link, number of posts)** +```` list? List of hierarchies **(name, full name, path, link, indent levels, indent to change before, indent to change after)** +```` 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 index 44d8587811..5fae31647d 100644 --- 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"