new: usr: added priority option to change plugin priority (refs #38)

Now the plugin execution priority can be changed if you don't like
default value.
The default should be the most reasonable with most plugins.

README.md

@@ -106,7 +106,7 @@ For [Gentoo Linux][Gentoo] there is an ebuild at http://gpo.zugaina.org/dev-util
 the ebuild and the `files` subfolder or you can add the `zugaina` repository with [layman][]
 (recommended).
 
-### Using a PlantUML server
+### <a name="using-plantuml-server"></a>Using a PlantUML server
 
 From version `2.0` a [PlantUML server](http://plantuml.com/server) can be used for rendering diagrams. This speedups a
 lot the diagrams rendering but needs to send the diagram source to a server.
@@ -125,11 +125,30 @@ plantuml_markdown:
   classes: class1,class2                    # default diagram classes
   title: UML diagram                        # default title (tooltip) for diagram images
   alt: UML diagram image                    # default `alt` attribute for diagram images
+  priority: 30                              # plugin priority; the higher, the sooner will be applied (default 30)
 ```
 
 Then you need to specify the configuration file on the command line:
 
     markdown_py -x plantuml_markdown -c myconfig.yml mydoc.md > out.html
+
+Plugin options
+--------------
+
+The plugin has several configuration option:
+
+* `classes`: space separated list of classes for the generated image. Defaults to `uml`
+* `format`: format of image to generate (`png`, `svg` or `txt`). Defaults to `png`
+* `alt`: text to show when image is not available. Defaults to `uml diagram`
+* `title`: tooltip for the diagram
+* `server`: PlantUML server url, for remote rendering. Defaults to `''`, use local command
+* `cachedir`: directory for caching of diagrams. Defaults to `''`, no caching
+* `priority`: extension priority. Higher values means the extension is applied sooner than others. Defaults to `30`
+
+For passing options to the `plantuml_plugin` see the documentation of the tool you are using.
+
+For `markdown_py`, simply write a YAML file with the configurations and use the `-c` option on the command line.
+See the [Using a PlantUML server](#using-plantuml-server) section for an example.
 
 Running tests
 -------------

plantuml_markdown.py

@@ -256,7 +256,9 @@ def __init__(self, **kwargs):
             'format': ["png", "Format of image to generate (png, svg or txt). Defaults to 'png'."],
             'title': ["", "Tooltip for the diagram"],
             'server': ["", "PlantUML server url, for remote rendering. Defaults to '', use local command."],
-            'cachedir': ["", "Directory for caching of diagrams. Defaults to '', no caching"]
+            'cachedir': ["", "Directory for caching of diagrams. Defaults to '', no caching"],
+            'priority': ["30", "Extension priority. Higher values means the extension is applied sooner than others. "
+                               "Defaults to 30"]
         }
 
         # Fix to make links navigable in SVG diagrams
@@ -272,7 +274,7 @@ def extendMarkdown(self, md, md_globals=None):
         if markdown.version_info[0] < 3:
             md.preprocessors.add('plantuml', blockprocessor, '_begin')
         else:
-            md.preprocessors.register(blockprocessor, 'plantuml', 100)
+            md.preprocessors.register(blockprocessor, 'plantuml', int(blockprocessor.config['priority']))
 
 
 def makeExtension(**kwargs):

test-requirements.txt

@@ -1 +1,2 @@
 unittest2
+pymdown-extensions

test/test_plantuml.py

@@ -1,20 +1,23 @@
 # -*- coding: utf-8 -*-
 import os
 import re
-import unittest
+#import unittest
 import markdown
+import tempfile
+from unittest import TestCase, SkipTest, mock
 
 
-class PlantumlTest(unittest.TestCase):
+class PlantumlTest(TestCase):
 
     @classmethod
     def setUpClass(cls):
         if cls is PlantumlTest:
-            raise unittest.SkipTest("Base class")
+            raise SkipTest("Base class")
         super(PlantumlTest, cls).setUpClass()
 
     def setUp(self):
-        self.md = markdown.Markdown(extensions=['markdown.extensions.fenced_code', 'plantuml_markdown'])
+        self.md = markdown.Markdown(extensions=['markdown.extensions.fenced_code',
+                                                'pymdownx.snippets', 'plantuml_markdown'])
         self.text_builder = None
 
     def _load_file(self, filename):
@@ -57,6 +60,53 @@ def sort_attributes(groups):
 
         return cls.SVG_REGEX.sub(lambda x: sort_attributes(x.groups()), html)
 
+    def test_priority_after_snippets(self):
+        """
+        Verifies the normal priority of the plantuml_markdown plugin: it must be execute before the fenced code
+        but after the snippets plugin.
+        """
+        self._test_snippets(30, 'A --> B\n')
+
+    def test_priority_before_snippets(self):
+        """
+        Verifies changing plugin priority: in must be execute even before the snippets plugin.
+        :return:
+        """
+        # raising priority, so the plantuml plugin is executed before the snippet plugin
+        # expecting that the snippet is not inserted in the plantuml source code
+        self._test_snippets(40, '--8<-- "'+os.path.join(tempfile.gettempdir(), 'test-defs.puml')+'"\n')
+
+    def _test_snippets(self, priority, expected):
+        """
+        Verifies the execution order with the snippets plugin.
+        If priority is lower than 32, the snippets plugin has priority; if greater, the
+        plantml_markdown plugin has priority over the snippets plugin.
+        :param priority: execution priority of the plantuml_markdown plugin
+        :param expected: expected generated plantuml source code
+        """
+        self.md = markdown.Markdown(extensions=['markdown.extensions.fenced_code',
+                                                'pymdownx.snippets', 'plantuml_markdown'],
+                                    extension_configs={
+                                        'plantuml_markdown': {
+                                            'priority': priority
+                                        }
+                                    })
+        tempdir = tempfile.gettempdir()
+        defs_file = os.path.join(tempdir, 'test-defs.puml')
+        # preparing a file to include
+        with open(defs_file, 'w') as f:
+            f.write('A --> B')
+
+        from test.markdown_builder import MarkdownBuilder
+        from plantuml_markdown import PlantUMLPreprocessor
+
+        # mcking a method to capture the generated PlantUML source code
+        with mock.patch.object(PlantUMLPreprocessor, '_render_diagram',
+                            return_value='testing'.encode('utf8')) as mocked_plugin:
+            text = self.text_builder.diagram("--8<-- \"" + defs_file + "\"").build()
+            self.md.convert(text)
+            mocked_plugin.assert_called_with(expected, 'png')
+
     def test_arg_title(self):
         """
         Test for the correct parsing of the title argument