ImagineUI macro preprocessor that replaces tags with PNGs rendered vi…

…a imagineui-cli

.gitignore

@@ -0,0 +1,103 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+.idea

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 wave909.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,76 @@
+[![](https://img.shields.io/pypi/v/foliantcontrib.imagineui.svg)](https://pypi.org/project/foliantcontrib.imagineui/) [![](https://img.shields.io/github/v/tag/imagineui/foliantcontrib.imagineui.svg?label=GitHub)](https://github.com/imagineui/foliantcontrib.imagineui)
+
+# ImagineUI for Foliant
+
+ImagineUI is a tool that supports developing wireframes in a localized human-readable format.
+
+This preprocessor allows using `<imagineui>` macros in Foliant
+
+## Installation
+
+Before using ImagineUI, you need to install [Node.js](https://nodejs.org/en/).
+
+ImagineUI preprocessor code is written in Python, but it uses a JavaScript package. This script is provided in ImagineUI package:
+
+```bash
+$ pip install foliantcontrib.imagineui
+```
+
+ImagineUI uses Puppeteer for rendering in background, which is a huge dependency, so to avoid downloading Chrome every time this preprocessor applies, it's advised to install `imagineui-cli` globally.
+
+```bash
+$ npm i -g imagineui-cli 
+```
+
+## Config
+
+To enable the preprocessor, add `imagineui` to `preprocessors` section in the project config:
+
+```yaml
+preprocessors:
+    - imagineui
+```
+
+The preprocessor has a number of options with the following default values:
+
+```yaml
+preprocessors:
+    - imagineui:
+        version: global
+        cache_dir: !path .imagineuicache
+```
+
+`version`
+:   Version of the `imagineui-cli` package in NPM. "global" (default) will skip and will use either the version already installed globally or the latest version, which speeds up NPX significantly. 
+
+`cache_dir`
+:   Directory to store downloaded and resized images.
+
+## Usage
+
+To insert a wireframe image rendered by ImagineUI into your documentation, use `<imagineui>...</imagineui>` tags in Markdown source:
+
+```markdown
+<imagineui>
+    Page: "Welcome screen"
+    Block: "Header"
+        Header "Mockup poetry"
+    Block: "Flowers"
+        Two columns
+            Image "Roses are red,"
+            Image "Violets are blue."
+            Image "Your mockups are awesome,"
+            Image "And so are you!"
+    Block: "Footer"
+        One row
+            Button "Try ImagineUI"
+            Button "Subscribe"
+            Button "Contribute"
+</imagineui>
+```
+
+ImagineUI preprocessor will replace such blocks with local image references.
+
+
+## Acknowledgements
+[BindSympli](https://github.com/foliant-docs/foliantcontrib.bindsympli) preprocessor was used as a starting point

foliant/preprocessors/imagineui.py

@@ -0,0 +1,115 @@
+'''
+Preprocessor for Foliant documentation authoring tool.
+Renders ImagineUI wireframes and inserts them into documents.
+
+Uses Node.js, headless Chrome, Puppeteer and ImagineUI.
+'''
+
+import re
+from pathlib import Path
+from hashlib import md5
+from subprocess import run, PIPE, STDOUT, CalledProcessError
+from time import sleep
+from typing import Dict
+
+OptionValue = int or float or bool or str
+
+from foliant.utils import output
+from foliant.preprocessors.base import BasePreprocessor
+
+
+class Preprocessor(BasePreprocessor):
+    defaults = {
+        'version': 'latest',
+        'cache_dir': Path('.imagineuicache'),
+    }
+
+    tags = 'imagineui',
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self._cache_dir_path = (self.project_path / self.options['cache_dir']).resolve()
+
+        self.logger = self.logger.getChild('imagineui')
+
+        self.logger.debug(f'Preprocessor inited: {self.__dict__}')
+
+    def _scene_filepath(self, name):
+        return f'{self._cache_dir_path}/{name}.scene'
+
+    def _rendered_scene_filepath(self, name):
+        return f'{self._cache_dir_path}/{name}.png'
+
+    def _process_imagineui(self, name: str) -> str:
+        # TODO: Get caption from IUI syntax
+        return f'![ImagineUI Render]({self._rendered_scene_filepath(name)})'
+
+    i = -1
+
+    def _get_substitution_count(self):
+        self.i += 1
+        return self.i
+
+    def process_imagineui(self, markdown_content: str) -> str:
+        def _sub(wireframe_definition) -> str:
+            return self._process_imagineui(f"{self._get_substitution_count()}")
+
+        return self.pattern.sub(_sub, markdown_content)
+
+    def apply(self):
+        self.logger.info('Applying preprocessor')
+
+        wireframe_files = []
+
+        # fixme: hash .scene file names
+        i = 0
+        for markdown_file_path in self.working_dir.rglob('*.md'):
+            with open(markdown_file_path, encoding='utf8') as markdown_file:
+                markdown_content = markdown_file.read()
+
+            wireframe_definitions = re.finditer(self.pattern, markdown_content)
+
+            for wireframe_definition in wireframe_definitions:
+                wireframe_file_path = self._scene_filepath(i)
+                i += 1
+                with open(wireframe_file_path, 'w', encoding='utf8') as wireframe_file:
+                    wireframe_file.write(wireframe_definition.group('body').strip())
+                wireframe_files.append(wireframe_file_path)
+
+        self.logger.debug(f'Wireframe files: {wireframe_files}')
+
+        if wireframe_files:
+            self._cache_dir_path.mkdir(parents=True, exist_ok=True)
+
+            output('Running ImagineUI CLI', self.quiet)
+
+            input_param = " ".join(map(lambda x: f'--input=' + x, wireframe_files))
+
+            ver = self.options["version"]
+            package_name = "imagineui-cli"
+            if ver and ver != "latest":
+                package_name = f'imagineui-cli@{self.options["version"]}'
+
+            command = (
+                    f'npx {package_name} ' +
+                    f'--outputDir={self._cache_dir_path} ' +
+                    input_param
+            )
+
+            command_output = run(command, shell=True, check=True, stdout=PIPE, stderr=STDOUT)
+
+            if command_output.stdout:
+                output(command_output.stdout.decode('utf8', errors='ignore'), self.quiet)
+
+            for markdown_file_path in self.working_dir.rglob('*.md'):
+                with open(markdown_file_path, encoding='utf8') as markdown_file:
+                    markdown_content = markdown_file.read()
+
+                processed_content = self.process_imagineui(markdown_content)
+
+                if processed_content:
+                    with open(markdown_file_path, 'w', encoding='utf8') as markdown_file:
+                        markdown_file.write(processed_content)
+
+        self.logger.info('Preprocessor applied')

setup.py

@@ -0,0 +1,39 @@
+from setuptools import setup
+
+
+SHORT_DESCRIPTION = 'ImagineUI integration preprocessor for Foliant.'
+
+try:
+    with open('README.md', encoding='utf8') as readme:
+        LONG_DESCRIPTION = readme.read()
+
+except FileNotFoundError:
+    LONG_DESCRIPTION = SHORT_DESCRIPTION
+
+
+setup(
+    name='foliantcontrib.imagineui',
+    description=SHORT_DESCRIPTION,
+    long_description=LONG_DESCRIPTION,
+    long_description_content_type='text/markdown',
+    version='1.0.0',
+    author='Vadim Smelianskii',
+    author_email='[email protected]',
+    url='https://github.com/imagineui/foliantcontrib.imagineui',
+    packages=['foliant.preprocessors'],
+    license='MIT',
+    install_requires=[
+        'foliant>=1.0.8'
+    ],
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Environment :: Console",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: POSIX :: Linux",
+        "Operating System :: MacOS",
+        "Programming Language :: Python",
+        "Topic :: Documentation",
+        "Topic :: Utilities",
+    ]
+)