Merge 70e0302 into 8b6f349

nikola/nikola.py

@@ -73,6 +73,7 @@
     SignalHandler,
     ConfigPlugin,
     PostScanner,
+    Taxonomy,
 )
 
 if DEBUG:
@@ -948,6 +949,7 @@ def init_plugins(self, commands_only=False, load_all=False):
             "SignalHandler": SignalHandler,
             "ConfigPlugin": ConfigPlugin,
             "PostScanner": PostScanner,
+            "Taxonomy": Taxonomy,
         })
         self.plugin_manager.getPluginLocator().setPluginInfoExtension('plugin')
         extra_plugins_dirs = self.config['EXTRA_PLUGINS_DIRS']
@@ -1019,6 +1021,7 @@ def plugin_position_in_places(plugin):
 
         self.plugin_manager.loadPlugins()
 
+        self._activate_plugins_of_category("Taxonomy")
         self._activate_plugins_of_category("SignalHandler")
 
         # Emit signal for SignalHandlers which need to start running immediately.

nikola/plugin_categories.py

@@ -49,6 +49,7 @@
     'SignalHandler',
     'ConfigPlugin',
     'PostScanner',
+    'Taxonomy',
 )
 
 
@@ -451,3 +452,173 @@ def import_file(self):
     def save_post(self):
         """Save a post to disk."""
         raise NotImplementedError()
+
+
+class Taxonomy(BasePlugin):
+    """Taxonomy for posts.
+
+    A taxonomy plugin allows to classify posts (see #2107) by
+    classification strings.
+    """
+
+    name = "dummy_taxonomy"
+
+    # Adjust the following values in your plugin!
+
+    # The classification name to be used for path handlers.
+    classification_name = "taxonomy"
+    # The classification name to be used when storing the classification
+    # in the metadata. If set to None, the classification won't be stored
+    # in the metadata.
+    metadata_name = "taxonomy"
+    # Variable for the overview page template which contains the list of
+    # classifications.
+    overview_page_variable_name = "taxonomy"
+    # If True, there can be more than one classification per post; in that case,
+    # the classification data in the metadata is stored as a list. If False,
+    # the classification data in the metadata is stored as a string, or None
+    # when no classification is given.
+    more_than_one_classifications_per_post = False
+    # Whether the classification has a hierarchy.
+    has_hierarchy = False
+    # If True, the list for a classification includes all posts with a
+    # sub-classification (in case has_hierarchy is True).
+    include_posts_from_subhierarchies = False
+    # Whether to show the posts for one classification as an index or
+    # as a post list.
+    show_list_as_index = False
+    # The template to use for the post list for one classification.
+    # Set to none to avoid generating overviews.
+    template_for_list_of_one_classification = "tagindex.tmpl"
+    # The template to use for the classification overview page.
+    template_for_classification_overview = "list.tmpl"
+    # Whether this classification applies to posts.
+    apply_to_posts = True
+    # Whether this classification applies to pages.
+    apply_to_pages = False
+    # The minimum number of posts a classification must have to be listed in
+    # the overview.
+    minimum_post_count_per_classification_in_overview = 1
+    # Whether post lists resp. indexes should be created for empty
+    # classifications.
+    omit_empty_classifications = False
+    # Whether to include all classifications for all languages in every
+    # language, or only the classifications for one language in its language's
+    # pages.
+    also_create_classifications_from_other_languages = True
+
+    def is_enabled(self, lang=None):
+        """Return True if this taxonomy is enabled, or False otherwise.
+
+        If lang is None, this determins whether the classification is
+        made at all. If lang is not None, this determines whether the
+        overview page and the classification lists are created for this
+        language.
+        """
+        return True
+
+    def classify(self, post, lang):
+        """Classify the given post for the given language.
+
+        Must return a list or tuple of strings.
+        """
+        raise NotImplementedError()
+
+    def sort_posts(self, posts, classification, lang):
+        """Sort the given list of posts.
+
+        The sort must happen in-place.
+        """
+        pass
+
+    def sort_classifications(self, classifications, lang):
+        """Sort the given list of classification strings.
+
+        For hierarchical taxonomies, the elements of the list are a single
+        path element of the path returned by extract_hierarchy().
+
+        The sort must happen in-place.
+        """
+        pass
+
+    def get_list_path(self, lang, type='page'):
+        """A path handler for the list of all classifications.
+
+        Must return a list or tuple, together with a boolean indicating
+        whether INDEX_FILE should always be added (True) or not (False).
+
+        In case INDEX_FILE should not be added, the last element in the returned
+        path must have no extension, and the PRETTY_URLS config must be ignored
+        by this handler. The return value will be modified based on the
+        PRETTY_URLS and INDEX_FILE settings.
+
+        Type can be either 'page', 'feed' (for Atom feed) or 'rss'.
+        """
+        raise NotImplementedError()
+
+    def get_path(self, classification, lang, type='page'):
+        """A path handler for the given classification.
+
+        Must return a list or tuple, together with a boolean indicating
+        whether INDEX_FILE should always be added (True) or not (False).
+
+        In case INDEX_FILE should not be added, the last element in the returned
+        path must have no extension, and the PRETTY_URLS config must be ignored
+        by this handler. The return value will be modified based on the
+        PRETTY_URLS and INDEX_FILE settings.
+
+        Type can be either 'page', 'feed' (for Atom feed) or 'rss'.
+
+        For hierarchical taxonomies, the result of extract_hierarchy is provided
+        as `classification`. For non-hierarchical taxonomies, the classification
+        string itself is provided as `classification`.
+        """
+        raise NotImplementedError()
+
+    def extract_hierarchy(self, classification):
+        """Given a classification, return a list of parts in the hierarchy.
+
+        For non-hierarchical taxonomies, it usually suffices to return
+        `[classification]`.
+        """
+        return [classification]
+
+    def recombine_classification_from_hierarchy(self, hierarchy):
+        """Given a list of parts in the hierarchy, return the classification string.
+
+        For non-hierarchical taxonomies, it usually suffices to return hierarchy[0].
+        """
+        return hierarchy[0]
+
+    def provide_list_context_and_uptodate(self, lang):
+        """Provide data for the context and the uptodate list for the list of all classifiations.
+
+        Must return a tuple of two dicts. The first is merged into the page's context,
+        the second will be put into the uptodate list of all generated tasks.
+
+        Context must contain `title`.
+        """
+        raise NotImplementedError()
+
+    def provide_context_and_uptodate(self, classification, lang):
+        """Provide data for the context and the uptodate list for the list of the given classifiation.
+
+        Must return a tuple of two dicts. The first is merged into the page's context,
+        the second will be put into the uptodate list of all generated tasks.
+
+        Context must contain `title`, which should be something like 'Posts about <classification>',
+        and `classification_title`, which should be related to the classification string.
+        """
+        raise NotImplementedError()
+
+    def postprocess_posts_per_classification(self, posts_per_classification_per_language, flat_hierarchy_per_lang=None, hierarchy_lookup_per_lang=None):
+        """Rearrange, modify or otherwise use the list of posts per classification and per language.
+
+        For compatibility reasons, the list could be stored somewhere else as well.
+
+        In case `has_hierarchy` is `True`, `flat_hierarchy_per_lang` is the flat
+        hierarchy consisting of `utils.TreeNode` elements, and `hierarchy_lookup_per_lang`
+        is the corresponding hierarchy lookup mapping classification strings to
+        `utils.TreeNode` objects.
+        """
+        pass

nikola/plugins/misc/taxonomies_classifier.plugin

@@ -0,0 +1,12 @@
+[Core]
+name = classify_taxonomies
+module = taxonomies_classifier
+
+[Documentation]
+author = Roberto Alsina
+version = 1.0
+website = https://getnikola.com/
+description = Classifies the timeline into taxonomies.
+
+[Nikola]
+plugincategory = SignalHandler