Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Improving various documentations and namings.
  • Loading branch information
felixfontein committed Nov 27, 2016
1 parent 0a3927d commit 2e88e02
Show file tree
Hide file tree
Showing 8 changed files with 67 additions and 36 deletions.
28 changes: 18 additions & 10 deletions nikola/plugin_categories.py
Expand Up @@ -482,7 +482,8 @@ class Taxonomy(BasePlugin):
a set of options to determine certain aspects.
The following options are class attributes with their default
values:
values. These variables should be set in the class definition,
in the constructor or latest in the `set_site` function.
classification_name = "taxonomy":
The classification name to be used for path handlers.
Expand All @@ -493,8 +494,8 @@ class Taxonomy(BasePlugin):
in the metadata.
overview_page_variable_name = "taxonomy":
Variable for the overview page template which contains the list of
classifications.
When rendering the overview page, its template will have a list
of classifications available in a variable by this name.
more_than_one_classifications_per_post = False:
If True, there can be more than one classification per post; in that case,
Expand Down Expand Up @@ -528,7 +529,7 @@ class Taxonomy(BasePlugin):
generate_atom_feeds_for_post_lists = False:
Whether to generate Atom feeds for post lists in case GENERATE_ATOM is set.
template_for_list_of_one_classification = "tagindex.tmpl":
template_for_single_list = "tagindex.tmpl":
The template to use for the post list for one classification.
template_for_classification_overview = "list.tmpl":
Expand Down Expand Up @@ -571,7 +572,7 @@ class Taxonomy(BasePlugin):
show_list_as_subcategories_list = False
show_list_as_index = False
generate_atom_feeds_for_post_lists = False
template_for_list_of_one_classification = "tagindex.tmpl"
template_for_single_list = "tagindex.tmpl"
template_for_classification_overview = "list.tmpl"
always_disable_rss = False
apply_to_posts = True
Expand Down Expand Up @@ -604,23 +605,30 @@ def classify(self, post, lang):
def sort_posts(self, posts, classification, lang):
"""Sort the given list of posts.
The sort must happen in-place.
Allows the plugin to order the posts per classification as it wants.
The posts will be ordered by date (latest first) before calling
this function. This function must sort in-place.
"""
pass

def sort_classifications(self, classifications, lang, level=None):
"""Sort the given list of classification strings.
Allows the plugin to order the classifications as it wants. The
classifications will be ordered by `natsort` before calling this
function. This function must sort in-place.
For hierarchical taxonomies, the elements of the list are a single
path element of the path returned by `extract_hierarchy()`. The index
of the path element in the path will be provided in `level`.
The sort must happen in-place.
"""
pass

def get_classification_printable_name(self, classification, lang, only_last_component=False):
"""Extract a printable name from the classification.
def get_classification_friendly_name(self, classification, lang, only_last_component=False):
"""Extract a friendly name from the classification.
The result of this function is usually displayed to the user, instead
of using the classification string.
For hierarchical taxonomies, the result of extract_hierarchy is provided
as `classification`. For non-hierarchical taxonomies, the classification
Expand Down
43 changes: 33 additions & 10 deletions nikola/plugins/misc/taxonomies_classifier.py
Expand Up @@ -44,7 +44,10 @@ class TaxonomiesClassifier(SignalHandler):
name = "render_taxonomies"

def _do_classification(self, site):
taxonomies = [p.plugin_object for p in site.plugin_manager.getPluginsOfCategory('Taxonomy') if p.plugin_object.is_enabled()]
# Get list of enabled taxonomy plugins
taxonomies = [p.plugin_object for p in site.plugin_manager.getPluginsOfCategory('Taxonomy')]
taxonomies = [taxonomy for taxonomy in taxonomies if taxonomy.is_enabled()]
# Prepare classification and check for collisions
site.posts_per_classification = {}
for taxonomy in taxonomies:
if taxonomy.classification_name in site.posts_per_classification:
Expand Down Expand Up @@ -189,23 +192,38 @@ def create_hierarchy(hierarchy, parent=None, level=0):
else:
taxonomy.postprocess_posts_per_classification(site.posts_per_classification[taxonomy.classification_name])

def _filter_list(self, post_list, lang):
"""Return only the posts which should be shown for this language."""
def _get_filtered_list(self, taxonomy, classification, lang):
"""Return the filtered list of posts for this classification and language."""
post_list = self.site.posts_per_classification[taxonomy.classification_name][lang].get(classification, [])
if self.site.config["SHOW_UNTRANSLATED_POSTS"]:
return post_list
else:
return [x for x in post_list if x.is_translation_available(lang)]

def _get_filtered_list(self, taxonomy, classification, lang):
"""Return the filtered list of posts for this classification and language."""
return self._filter_list(self.site.posts_per_classification[taxonomy.classification_name][lang].get(classification, []), lang)

@staticmethod
def _compute_number_of_pages(self, filtered_posts, posts_count):
def _compute_number_of_pages(filtered_posts, posts_count):
"""Given a list of posts and the maximal number of posts per page, computes the number of pages needed."""
return min(1, (len(filtered_posts) + posts_count - 1) // posts_count)

def _postprocess_path(self, path, lang, append_index='auto', type='page', page_info=None):
"""Postprocess a generated path.
Takes the path `path` for language `lang`, and postprocesses it.
It appends `site.config['INDEX_FILE']` depending on `append_index`
(which can have the values `'always'`, `'never'` and `'auto'`) and
`site.config['PRETTY_URLS']`.
It also modifies/adds the extension of the last path element resp.
`site.config['INDEX_FILE']` depending on `type`, which can be
`'feed'`, `'rss'` or `'page'`.
Finally, if `type` is `'page'`, `page_info` can be `None` or a tuple
of two integers: the page number and the number of pages. This will
be used to append the correct page number by calling
`utils.adjust_name_for_index_path_list` and
`utils.get_displayed_page_number`.
"""
# Forcing extension for Atom feeds and RSS feeds
force_extension = None
if type == 'feed':
Expand Down Expand Up @@ -240,7 +258,10 @@ def _parse_path_result(result):
if not isinstance(result[0], (list, tuple)):
# The result must be a list or tuple of strings. Wrap into a tuple
result = (result, )
return result[0], result[1] if len(result) > 1 else 'auto', result[2] if len(result) > 2 else None
path = result[0]
append_index = result[1] if len(result) > 1 else 'auto'
page_info = result[2] if len(result) > 2 else None
return path, append_index, page_info

def _taxonomy_index_path(self, lang, taxonomy):
"""Return path to the classification overview."""
Expand Down Expand Up @@ -284,5 +305,7 @@ def set_site(self, site):
# Add hook for after post scanning
blinker.signal("scanned").connect(self._do_classification)
# Register path handlers
for taxonomy in [p.plugin_object for p in site.plugin_manager.getPluginsOfCategory('Taxonomy') if p.plugin_object.is_enabled()]:
for taxonomy in [p.plugin_object for p in site.plugin_manager.getPluginsOfCategory('Taxonomy')]:
if not taxonomy.is_enabled():
continue
self._register_path_handlers(taxonomy)
6 changes: 3 additions & 3 deletions nikola/plugins/task/archive.py
Expand Up @@ -61,7 +61,7 @@ def set_site(self, site):
# Finish setup
self.show_list_as_subcategories_list = False if site.config['CREATE_FULL_ARCHIVES'] else "list.tmpl"
self.show_list_as_index = site.config['ARCHIVES_ARE_INDEXES']
self.template_for_list_of_one_classification = "archiveindex.tmpl" if site.config['ARCHIVES_ARE_INDEXES'] else "list_post.tmpl"
self.template_for_single_list = "archiveindex.tmpl" if site.config['ARCHIVES_ARE_INDEXES'] else "list_post.tmpl"
# Determine maximal hierarchy height
if site.config['CREATE_DAILY_ARCHIVE'] or site.config['CREATE_FULL_ARCHIVES']:
self.max_levels = 3
Expand Down Expand Up @@ -94,8 +94,8 @@ def sort_classifications(self, classifications, lang, level=None):
classifications.sort()
classifications.reverse()

def get_classification_printable_name(self, classification, lang, only_last_component=False):
"""Extract a printable name from the classification."""
def get_classification_friendly_name(self, classification, lang, only_last_component=False):
"""Extract a friendly name from the classification."""
if len(classification) == 0:
return ""
elif len(classification) == 1:
Expand Down
6 changes: 3 additions & 3 deletions nikola/plugins/task/authors.py
Expand Up @@ -53,7 +53,7 @@ class ClassifyAuthors(Taxonomy):
def set_site(self, site):
"""Set Nikola site."""
self.show_list_as_index = site.config['AUTHOR_PAGES_ARE_INDEXES']
self.template_for_list_of_one_classification = "authorindex.tmpl" if self.show_list_as_index else "author.tmpl"
self.template_for_single_list = "authorindex.tmpl" if self.show_list_as_index else "author.tmpl"
return super(ClassifyAuthors, self).set_site(site)

def is_enabled(self, lang=None):
Expand All @@ -68,8 +68,8 @@ def classify(self, post, lang):
"""Classify the given post for the given language."""
return [post.author()]

def get_classification_printable_name(self, author, lang, only_last_component=False):
"""Extract a printable name from the classification."""
def get_classification_friendly_name(self, author, lang, only_last_component=False):
"""Extract a friendly name from the classification."""
return author

def get_list_path(self, lang, type='page'):
Expand Down
6 changes: 3 additions & 3 deletions nikola/plugins/task/indexes.py
Expand Up @@ -42,7 +42,7 @@ class Indexes(Taxonomy):
more_than_one_classifications_per_post = False
has_hierarchy = False
show_list_as_index = True
template_for_list_of_one_classification = "index.tmpl"
template_for_single_list = "index.tmpl"
template_for_classification_overview = None
apply_to_posts = True
apply_to_pages = False
Expand All @@ -63,8 +63,8 @@ def classify(self, post, lang):
"""Classify the given post for the given language."""
return [""]

def get_classification_printable_name(self, classification, lang, only_last_component=False):
"""Extract a printable name from the classification."""
def get_classification_friendly_name(self, classification, lang, only_last_component=False):
"""Extract a friendly name from the classification."""
return self.site.config["BLOG_TITLE"](lang)

def get_path(self, classification, lang, type='page'):
Expand Down
6 changes: 3 additions & 3 deletions nikola/plugins/task/page_index.py
Expand Up @@ -44,7 +44,7 @@ class PageIndex(Taxonomy):
include_posts_from_subhierarchies = False
show_list_as_index = False
generate_atom_feeds_for_post_lists = False
template_for_list_of_one_classification = "list.tmpl"
template_for_single_list = "list.tmpl"
template_for_classification_overview = None
always_disable_rss = True
apply_to_posts = False
Expand All @@ -65,8 +65,8 @@ def classify(self, post, lang):
i = destpath.rfind('/')
return destpath[:i] if i >= 0 else ''

def get_classification_printable_name(self, hierarchy, lang, only_last_component=False):
"""Extract a printable name from the classification."""
def get_classification_friendly_name(self, hierarchy, lang, only_last_component=False):
"""Extract a friendly name from the classification."""
return '/'.join(hierarchy)

def get_path(self, hierarchy, lang, type='page'):
Expand Down
6 changes: 3 additions & 3 deletions nikola/plugins/task/sections.py
Expand Up @@ -51,7 +51,7 @@ class ClassifySections(Taxonomy):
def set_site(self, site):
"""Set Nikola site."""
self.show_list_as_index = site.config["POSTS_SECTION_ARE_INDEXES"]
self.template_for_list_of_one_classification = "sectionindex.tmpl" if self.show_list_as_index else "list.tmpl"
self.template_for_single_list = "sectionindex.tmpl" if self.show_list_as_index else "list.tmpl"
self.enable_for_lang = {}
return super(ClassifySections, self).set_site(site)

Expand All @@ -74,8 +74,8 @@ def _get_section_name(self, section, lang):
else:
return section.replace('-', ' ').title()

def get_classification_printable_name(self, section, lang, only_last_component=False):
"""Extract a printable name from the classification."""
def get_classification_friendly_name(self, section, lang, only_last_component=False):
"""Extract a friendly name from the classification."""
return self._get_section_name(section, lang)

def get_path(self, section, lang, type='page'):
Expand Down
2 changes: 1 addition & 1 deletion nikola/plugins/task/taxonomies.py
Expand Up @@ -210,7 +210,7 @@ def _generate_subclassification_page(self, taxonomy, node, context, kw, lang):
"""Render a list of subclassifications."""
def get_subnode_data(subnode):
return [
taxonomy.get_classification_printable_name(subnode.classification_path, lang, only_last_component=True),
taxonomy.get_classification_friendly_name(subnode.classification_path, lang, only_last_component=True),
self.site.link(taxonomy.classification_name, subnode.classification_name, lang),
len(self._filter_list(self.site.posts_per_classification[taxonomy.classification_name][lang][subnode.classification_name], lang))
]
Expand Down

0 comments on commit 2e88e02

Please sign in to comment.