From db0a8677404a3239ede47672f7630f351e181aa7 Mon Sep 17 00:00:00 2001 From: Michele Tessaro Date: Fri, 6 Dec 2019 20:25:41 +0100 Subject: [PATCH] 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. --- .travis.yml | 1 + README.md | 21 +++++++++++++++- plantuml_markdown.py | 6 +++-- test-requirements.txt | 2 ++ test/test_plantuml.py | 58 ++++++++++++++++++++++++++++++++++++++++--- 5 files changed, 81 insertions(+), 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index 1ae9f8a..e101d86 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,6 +16,7 @@ install: - sudo apt-get install graphviz - pip install -r requirements.txt - pip install --upgrade Markdown==$MARKDOWN_VER + - pip install -r test-requirements.txt - wget 'http://sourceforge.net/projects/plantuml/files/plantuml.1.2018.2.jar/download' -O /tmp/plantuml.1.2018.2.jar script: diff --git a/README.md b/README.md index 605647f..2f1d496 100644 --- a/README.md +++ b/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 +### 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 ------------- diff --git a/plantuml_markdown.py b/plantuml_markdown.py index 7a62976..d99de20 100644 --- a/plantuml_markdown.py +++ b/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): diff --git a/test-requirements.txt b/test-requirements.txt index 9a23970..1ded410 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1 +1,3 @@ unittest2 +mock +pymdown-extensions diff --git a/test/test_plantuml.py b/test/test_plantuml.py index bdc8a4b..c5af8a9 100644 --- a/test/test_plantuml.py +++ b/test/test_plantuml.py @@ -1,20 +1,23 @@ # -*- coding: utf-8 -*- import os import re -import unittest import markdown +import tempfile +from unittest import TestCase, SkipTest +import 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