Merge pull request #24 from MikhailKravets/release/1.2.0

Release/1.2.0

.github/workflows/checks.yml

@@ -2,9 +2,9 @@ name: Test, Linter
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [ "master", "release/*", ]
   pull_request:
-    branches: [ "master", "release", "develop" ]
+    branches: [ "master", "release/*", ]
 
 jobs:
   test:

README.md

@@ -3,7 +3,7 @@
 [![PyPI version](https://badge.fury.io/py/mkdocs_puml.svg)](https://badge.fury.io/py/mkdocs_puml)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mkdocs_puml)](https://pypistats.org/packages/mkdocs-puml)
 
-`mkdocs_puml` is fast and simple package that brings plantuml diagrams to MkDocs
+`mkdocs_puml` is a fast and simple package that brings plantuml diagrams to MkDocs
 documentation.
 
 ## Install
@@ -19,19 +19,32 @@ pip install mkdocs_puml
 Just add `plantuml` plugin into `plugins` section of your `mkdocs.yml` file,
 in order to use puml with mkdocs.
 
-`plantuml` plugin uses `PlantUML` only as an http service. So, you should necessarily
+```yaml
+plugins:
+    - plantuml:
+        puml_url: https://www.plantuml.com/plantuml/
+```
+
+`plantuml` plugin uses `PlantUML` only as an HTTP service. So, you should necessarily
 specify `puml_url` config.
 
+The `plantuml` config with the full list of parameters is below
+
 ```yaml
 plugins:
     - plantuml:
         puml_url: https://www.plantuml.com/plantuml/
         num_workers: 8
+        puml_keyword: puml
 ```
 
 Where
-* `puml_url` is URL to the plantuml service.
-* `num_workers` is max amount of concurrent workers that request plantuml service.
+
+| Parmeter | Type                 | Descripton                                                     |
+|----------|----------------------|----------------------------------------------------------------|
+| `puml_url` | `str`. Required      | URL to the plantuml service                                    |
+| `num_workers` | `int`. Default `8`   | Max amount of concurrent workers that request plantuml service |
+| `puml_keyword` | `str`. Default `puml` | The keyword for PlantUML code fence, i.e. \```puml \```        |
 
 Now, you can put your puml diagrams into your `.md` documentation. For example,
 
@@ -118,8 +131,9 @@ code blocks. When `puml` code block is found it is saved to the buffer for
 a later request to PlantUML service. In this step, we replace `puml` block
 with the uuid.
 
-**NOTE** you must set `puml` keyword as an indicator that the plant uml
-is located in the block.
+**NOTE** you must set `puml` keyword as an indicator that the PlantUML diagram
+is located in the block. Default keyword can be changed for the custom one
+in `mkdocs.yml` config file by using `puml_keyword` parameter.
 
 After all pages are parsed, `plantuml` plugin requests PlantUML service
 with the collected diagrams. After the responses are received, the package

mkdocs_puml/__init__.py

@@ -1,3 +1,3 @@
 """Package that brings PlantUML to MkDocs"""
 
-__version__ = "1.1.1"
+__version__ = "1.2.0"

mkdocs_puml/plugin.py

@@ -30,17 +30,19 @@ class PlantUMLPlugin(BasePlugin):
         uuid_regex (re.Pattern): regex to find all uuid <pre> blocks
         puml (PlantUML): PlantUML instance that requests PlantUML service
         diagrams (dict): Dictionary containing the diagrams (puml and later svg) and their keys
+        puml_keyword (str): keyword used to find PlantUML blocks within Markdown files
     """
     div_class_name = "puml"
     pre_class_name = "diagram-uuid"
 
     config_scheme = (
         ('puml_url', Type(str, required=True)),
-        ('num_workers', Type(int, default=8))
+        ('num_workers', Type(int, default=8)),
+        ('puml_keyword', Type(str, default='puml'))
     )
 
     def __init__(self):
-        self.regex = re.compile(rf"```{self.div_class_name}(.+?)```", flags=re.DOTALL)
+        self.regex: typing.Optional[typing.Any] = None
         self.uuid_regex = re.compile(rf'<pre class="{self.pre_class_name}">(.+?)</pre>', flags=re.DOTALL)
 
         self.puml: typing.Optional[PlantUML] = None
@@ -61,6 +63,8 @@ def on_config(self, config: Config) -> Config:
             Full config of the mkdocs
         """
         self.puml = PlantUML(self.config['puml_url'], num_workers=self.config['num_workers'])
+        self.puml_keyword = self.config['puml_keyword']
+        self.regex = re.compile(rf"```{self.puml_keyword}(.+?)```", flags=re.DOTALL)
         return config
 
     def on_page_markdown(self, markdown: str, *args, **kwargs) -> str:
@@ -84,7 +88,7 @@ def on_page_markdown(self, markdown: str, *args, **kwargs) -> str:
             id_ = str(uuid.uuid4())
             self.diagrams[id_] = v
             markdown = markdown.replace(
-                f"```{self.div_class_name}{v}```",
+                f"```{self.puml_keyword}{v}```",
                 f'<pre class="{self.pre_class_name}">{id_}</pre>'
             )
 

mkdocs_puml/puml.py

@@ -97,7 +97,9 @@ def request(self, encoded_diagram: str) -> str:
             SVG representation of the diagram
         """
         resp = requests.get(urljoin(self.base_url, f"{self._format}/{encoded_diagram}"))
-        return resp.content.decode('utf-8')
+
+        # Use 'ignore' to strip non-utf chars
+        return resp.content.decode('utf-8', errors='ignore')
 
     def _clean_comments(self, content: str) -> str:
         return self._html_comment_regex.sub("", content)

tests/conftest.py

@@ -6,6 +6,8 @@
 
 
 BASE_PUML_URL = "https://mocked.org/"
+BASE_PUML_KEYWORD = "puml"
+CUSTOM_PUML_KEYWORD = "plantuml"
 TESTDATA_DIR = Path(__file__).resolve().parent.joinpath('testdata')
 
 

tests/plugins/conftest.py

@@ -8,7 +8,7 @@
 from mkdocs.config.config_options import Config
 
 from mkdocs_puml.plugin import PlantUMLPlugin
-from tests.conftest import BASE_PUML_URL, TESTDATA_DIR
+from tests.conftest import BASE_PUML_URL, CUSTOM_PUML_KEYWORD, TESTDATA_DIR
 
 
 def is_uuid_valid(uuid_str: str) -> bool:
@@ -34,6 +34,14 @@ def plugin_config():
     return c
 
 
+@pytest.fixture
+def plugin_config_custom_keyword():
+    c = Config(schema=PlantUMLPlugin.config_scheme)
+    c['puml_url'] = BASE_PUML_URL
+    c['puml_keyword'] = CUSTOM_PUML_KEYWORD
+    return c
+
+
 @pytest.fixture
 def plugin_environment():
     loader = jinja2.FileSystemLoader(searchpath=TESTDATA_DIR)
@@ -51,6 +59,18 @@ def plant_uml_plugin(plugin_config):
     return plugin
 
 
+@pytest.fixture
+def plant_uml_plugin_custom_keyword(plugin_config_custom_keyword):
+    plugin = PlantUMLPlugin()
+    c = Config(schema=plugin.config_scheme)
+    c['puml_url'] = BASE_PUML_URL
+    c['puml_keyword'] = CUSTOM_PUML_KEYWORD
+    plugin.config = c
+    plugin.on_config(c)
+
+    return plugin
+
+
 @pytest.fixture
 def diagrams_dict(diagram_and_encoded):
     return {

tests/plugins/test_plugin.py

@@ -1,6 +1,6 @@
 from mkdocs_puml.plugin import PlantUMLPlugin
 from mkdocs_puml.puml import PlantUML
-from tests.conftest import BASE_PUML_URL
+from tests.conftest import BASE_PUML_KEYWORD, BASE_PUML_URL, CUSTOM_PUML_KEYWORD
 from tests.plugins.conftest import is_uuid_valid
 
 
@@ -12,6 +12,18 @@ def test_on_config(plugin_config):
 
     assert isinstance(plugin.puml, PlantUML)
     assert plugin.puml.base_url == BASE_PUML_URL
+    assert plugin.puml_keyword == BASE_PUML_KEYWORD
+
+
+def test_on_config_custom_keyword(plugin_config_custom_keyword):
+    plugin = PlantUMLPlugin()
+    plugin.config = plugin_config_custom_keyword
+
+    plugin.on_config(plugin_config_custom_keyword)
+
+    assert isinstance(plugin.puml, PlantUML)
+    assert plugin.puml.base_url == BASE_PUML_URL
+    assert plugin.puml_keyword == CUSTOM_PUML_KEYWORD
 
 
 def test_on_page_markdown(plant_uml_plugin, md_lines):
@@ -26,6 +38,18 @@ def test_on_page_markdown(plant_uml_plugin, md_lines):
         assert "@startuml" in val and "@enduml" in val
 
 
+def test_on_page_markdown_custom_keyword(plant_uml_plugin_custom_keyword, md_lines):
+    plant_uml_plugin_custom_keyword.on_page_markdown("\n".join(md_lines))
+
+    assert len(plant_uml_plugin_custom_keyword.diagrams) == 1
+
+    for key in plant_uml_plugin_custom_keyword.diagrams.keys():
+        assert is_uuid_valid(key)
+
+    for val in plant_uml_plugin_custom_keyword.diagrams.values():
+        assert "@startuml" in val and "@enduml" in val
+
+
 def test_on_env(mock_requests, plant_uml_plugin, diagrams_dict, plugin_environment):
     plant_uml_plugin.diagrams = diagrams_dict
     plant_uml_plugin.on_env(plugin_environment)

tests/testdata/markdown.md

@@ -53,6 +53,14 @@ package user_devices {
 @enduml
 ```
 
+## This is the third diagram using custom keyword
+
+```plantuml
+@startuml
+A -> B
+@enduml
+```
+
 And here is just code
 
 ```python