Merge pull request #9 from neatc0der/release/v1.0

Release/v1.0

Author: neatc0der

.build/mkdocs_markmap_build/common.py

@@ -95,9 +95,14 @@ def get_assets_from_release(self) -> List[str]:
 
 
 class ChangelogLoader:
-    def __init__(self, changelog_path: Path = CHANGELOG_PATH) -> None:
-        self._changelog_path = changelog_path
+    def __init__(self, tag: str, changelog_path: Path = CHANGELOG_PATH) -> None:
+        self.tag = tag
+        self._path = changelog_path / f'{self.tag}.md'
 
+    @property
+    def path(self) -> Path:
+        return self._path
+
     def _drop_headline(self, content: str) -> str:
         headline_detected: bool = False
         text_started: bool = False
@@ -122,9 +127,9 @@ def _drop_headline(self, content: str) -> str:
 
         return '\n'.join(lines)
 
-    def get(self, release: str, drop_headline: bool = True) -> str:
+    def get(self, drop_headline: bool = True) -> str:
         try:
-            with open(self._changelog_path / f'{release}.md', 'r') as fp:
+            with open(self._path, 'r') as fp:
                 content = fp.read()
 
             if drop_headline:
@@ -133,5 +138,5 @@ def get(self, release: str, drop_headline: bool = True) -> str:
             return content
 
         except OSError as e:
-            print(f'unable to load changelog for release {release}: {e}')
+            print(f'unable to load changelog for release {self.tag}: {e}')
             sys.exit(1)

.build/mkdocs_markmap_build/release.py

@@ -1,10 +1,11 @@
 import sys
 from pprint import pprint
 from typing import Dict, List
+from time import sleep
+
 from github.Commit import Commit
 from github.GitAuthor import GitAuthor
 from github.GitCommit import GitCommit
-
 from github.GitRelease import GitRelease
 from github.GitReleaseAsset import GitReleaseAsset
 from github.InputGitAuthor import InputGitAuthor
@@ -18,11 +19,11 @@
 class ReleaseHandler(GithubHandler):
     def __init__(self, tag: str) -> None:
         super(ReleaseHandler, self).__init__(tag)
-        self._changelog = ChangelogLoader()
+        self._changelog = ChangelogLoader(tag)
         self._collector = AssetCollector()
 
     def create(self, commit: str = None, dry_run: bool = True):
-        release_message: str = self._changelog.get(self.tag)
+        release_message: str = self._changelog.get()
         assets: List[str] = self._collector.get_assets()
         tagger: GitAuthor = None
 
@@ -50,7 +51,6 @@ def create(self, commit: str = None, dry_run: bool = True):
                 f'tag "{self.tag}" already exists'
             assert self.tag not in (release.tag_name for release in self.repository.get_releases()), \
                 f'release "{self.tag}" already exists'
-
         except AssertionError as e:
             print(e)
             sys.exit(1)
@@ -66,6 +66,10 @@ def create(self, commit: str = None, dry_run: bool = True):
                 release_asset: GitReleaseAsset = release.upload_asset(asset)
                 print(f'Release asset "{release_asset.name}" uploaded: {release_asset.url}')
 
+             # Give github some time to sort things out with the new release.
+             # Otherwise the "published" event will not be triggered.
+            sleep(5)
+
             release = release.update_release(
                 name=self.tag,
                 message=release_message,
@@ -76,20 +80,16 @@ def create(self, commit: str = None, dry_run: bool = True):
     def delete(self):
         try:
             next(t for t in self.repository.get_tags() if t.name == self.tag)
-
         except StopIteration:
             print(f'Tag "{self.tag}" does not exist')
-
         else:
             self.repository.get_git_ref(f'tags/{self.tag}').delete()
             print(f'Tag "{self.tag}" deleted')
 
         try:
             release: GitRelease = next(r for r in self.repository.get_releases() if r.tag_name == self.tag)
-
         except StopIteration:
             print(f'Release "{self.tag}" does not exist')
-
         else:
             release.delete_release()
             print(f'Release "{self.tag}" deleted')

.github/workflows/verify.yml

@@ -0,0 +1,28 @@
+name: Verification Workflow
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Distribute
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Prepare Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8 
+
+      - name: Install Dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install -r requirements/build.txt
+          python3 setup.py install
+
+      - name: Verify Integrity
+        run: inv verify

README.md

@@ -1,5 +1,7 @@
 # mkdocs-markmap
 
+> Beautiful and simple mindmaps written in markdown.
+
 This is a plugin and an extension for [mkdocs](https://github.com/mkdocs/mkdocs/) to add [markmap](https://github.com/gera2ld/markmap).
 
 ## Prerequisits
@@ -9,7 +11,7 @@ This plugin was tested with, but is not limited to:
 * Python 3.8
 * mkdocs 1.1
 
-## How to integrate this?
+## Quickstart
 
 ### Install
 
@@ -21,6 +23,17 @@ pip install mkdocs-markmap
 
 Add this to `mkdocs.yml`:
 
+```yaml
+markdown_extensions:
+  - markmap:
+plugins:
+  - markmap:
+```
+
+## Advanced Settings
+
+There are more options available for `mkdocs.yml` (shown values are defaults):
+
 ```yaml
 markdown_extensions:
   - markmap:
@@ -43,7 +56,7 @@ extra_javascript:
   - https://unpkg.com/[email protected]/dist/index.min.js
 ```
 
-:warning: The urls needs contain one of these keywords to be considered as deviation from default:
+:warning: The urls need to contain one of these keywords to be considered as deviation from default:
 
 * `d3`
 * `markmap-lib`
@@ -81,7 +94,7 @@ Look at this beautiful mindmap:
 {!mindmap.mm.md!}
 ```
 
-But you _do_ need the plugin for that. Thus, don't forget to follow the setup example above.
+But you _do_ need the plugin for that. Thus, don't forget to follow the quickstart example above.
 
 ## Credits :clap:
 

changelog/v1.0.md

@@ -0,0 +1,6 @@
+# v1.0
+
+* Logger for all files
+* Javascript templates
+* Build workflow improvement
+* Readme update

mkdocs_markmap/__meta__.py

@@ -1,6 +1,6 @@
 PACKAGE_NAME = 'mkdocs_markmap'
 PROJECT_NAME = PACKAGE_NAME.replace('_', '-')
-PROJECT_VERSION = '0.3'
+PROJECT_VERSION = '1.0'
 
 OWNER = 'neatc0der'
 REPOSITORY_NAME = f'{OWNER}/{PROJECT_NAME}'

mkdocs_markmap/extension.py

@@ -1,12 +1,16 @@
-from pathlib import Path
+import logging
 import re
+from pathlib import Path
 from typing import AnyStr, Dict, List, Optional
 
 from markdown import Markdown
 from markdown.extensions import Extension
 from markdown.preprocessors import Preprocessor
 
 
+log = logging.getLogger('mkdocs.markmap')
+
+
 INCLUDE_SYNTAX = re.compile(r'\{!\s*(?P<path>.+?)\s*!\}')
 
 
@@ -41,7 +45,7 @@ def run(self, lines: List[str]) -> List[str]:
                         markmap: List[str] = r.readlines()
 
                 except Exception as e:
-                    print('Warning: could not include file {}. Ignoring statement. Error: {}'.format(path, e))
+                    log.error('unable to include file {}. Ignoring statement. Error: {}'.format(path, e))
                     lines[loc] = INCLUDE_SYNTAX.sub('',line)
                     break
 

mkdocs_markmap/plugin.py

@@ -1,3 +1,4 @@
+import logging
 import re
 from pathlib import Path
 from typing import Dict, Tuple
@@ -7,44 +8,19 @@
 from mkdocs.structure.pages import Page
 from mkdocs.config.base import Config
 from mkdocs.config.config_options import Type as PluginType
+from mkdocs.utils import copy_file
 
 from .defaults import MARKMAP
 from .utils import download
 
 
-# todo: move this to template
-SCRIPT_CONTENT = """
-const markdown{index} = '{content}';
-const svg{index} = document.querySelector('#{tag_id}');
-const root{index} = markmap_transformer.transform(markdown{index}).root;
-var m{index} = markmap.Markmap.create(svg{index}, null, root{index});
-
-m{index}.rescale(1).then(function() {{
-    svg{index}.parentElement.style.height = (svg{index}.getBBox().height + 10) + "px";
-    setTimeout(function() {{
-        // todo: this is a dirty workaround to center the mindmap within svg
-        while (svg{index}.firstChild) {{
-            svg{index}.removeChild(svg{index}.lastChild);
-        }}
-        m{index} = markmap.Markmap.create(svg{index}, null, root{index});
-    }}, 500);
-}});
-"""
-
-# todo: move this to static file
-STYLE_CONTENT = """
-div.markmap {
-    width: 100%;
-    min-height: 1em;
-    border: 1px solid grey;
-}
-.markmap > svg {
-    width: 100%;
-    height: 100%;
-}
-"""
+log = logging.getLogger('mkdocs.markmap')
 
 
+TEMPLATES_PATH: Path = Path(__file__).parent / 'templates'
+STYLE_PATH: Path = TEMPLATES_PATH / 'mkdocs-markmap.css'
+SCRIPT_PATH: Path = TEMPLATES_PATH / 'mkdocs-markmap.js'
+
 class MarkmapPlugin(BasePlugin):
     """
     Plugin for markmap support
@@ -78,42 +54,52 @@ def markmap(self) -> Dict[str, str]:
 
         return self._markmap
 
+    def _load_scripts(self, soup: BeautifulSoup, script_base_url: str, js_path: Path) -> None:
+        for script_url in self.markmap.values():
+            try:
+                src: str = script_base_url + download(js_path, script_url)
+            except Exception as e:
+                log.error(f'unable to download script: {script_url}')
+                src = script_url
+            
+            script: Tag = soup.new_tag('script', src=src, type='text/javascript')
+            soup.head.append(script)
+
+    @staticmethod
+    def _add_statics(soup: BeautifulSoup):
+        statics = (
+            (STYLE_PATH, 'style', 'text/css', 'head'),
+            (SCRIPT_PATH, 'script', 'text/javascript', 'body'),
+        )
+
+        for path, tag_name, text_type, attribute in statics:
+            tag: Tag = soup.new_tag(tag_name, type=text_type)
+            with open(path, 'r') as fp:
+                tag.string = fp.read()
+            getattr(soup, attribute).append(tag)    
+
     def on_post_page(self, output_content: str, config: Config, **kwargs) -> str:
         soup: BeautifulSoup = BeautifulSoup(output_content, 'html.parser')
         page: Page = kwargs.get('page')
 
-        script_base_url: str = re.sub(r'[^/]+?/', '../', re.sub(r'/+?', '/', page.url)) + 'js/'
-        js_path: Path = Path(config['site_dir']) / 'js'
         markmaps: ResultSet = soup.find_all('code', class_='language-markmap')
-        if any(markmaps):
-            for script_url in self.markmap.values():
-                src: str = script_base_url + download(js_path, script_url)
-                script: Tag = soup.new_tag('script', src=src, type='text/javascript')
-                soup.head.append(script)
-            
-            style: Tag = soup.new_tag('style', type='text/css')
-            style.string = STYLE_CONTENT
-            soup.head.append(style)
+        if not any(markmaps):
+            return output_content
 
-            script: Tag = soup.new_tag('script')
-            script.string = 'const markmap_transformer = new markmap.Transformer();'
-            soup.head.append(script)
+        script_base_url: str = re.sub(r'[^/]+?/', '../', re.sub(r'/+?', '/', page.url)) + 'js/'
+        js_path: Path = Path(config['site_dir']) / 'js'
+        self._load_scripts(soup, script_base_url, js_path)
+        self._add_statics(soup)
 
         for index, markmap in enumerate(markmaps):
             tag_id: str = f'markmap-{index}'
             markmap.parent.name = 'div'
-            markmap.parent['class'] = markmap.parent.get('class', []) + ['markmap']
+            markmap.parent['class'] = markmap.parent.get('class', []) + ['mkdocs-markmap']
+            markmap.parent['data-markdown']=markmap.text.replace('\n', '
')
             markmap.replaceWith(soup.new_tag(
                 'svg', 
                 id=tag_id, 
                 attrs={'class': 'markmap'},
             ))
-            script: Tag = soup.new_tag('script')
-            script.string = SCRIPT_CONTENT.format(
-                index=index,
-                tag_id=tag_id,
-                content=markmap.text.replace('\n', '\\n'),
-            )
-            soup.body.append(script)
 
         return str(soup)

mkdocs_markmap/templates/mkdocs-markmap.css

@@ -0,0 +1,9 @@
+div.mkdocs-markmap {
+    width: 100%;
+    min-height: 1em;
+    border: 1px solid grey;
+}
+.mkdocs-markmap > svg {
+    width: 100%;
+    height: 100%;
+}

mkdocs_markmap/templates/mkdocs-markmap.js

@@ -0,0 +1,25 @@
+(function initializeMarkmap() {
+    const markmap_transformer = new markmap.Transformer();
+    const markmaps = document.getElementsByClassName('mkdocs-markmap');
+    var el, content, svg, root, m;
+    for (var i = 0; i < markmaps.length; i++) {
+        el = markmaps[i];
+        content = el.getAttribute('data-markdown').replaceAll('&#10;', '\n');
+        svg = el.querySelector('svg');
+        root = markmap_transformer.transform(content).root;
+        m = markmap.Markmap.create(svg, null, root);
+
+        // todo: this is a dirty workaround to center the mindmap within svg
+        (function(obj, e, r) {
+            obj.rescale(1).then(function() {
+                e.parentElement.style.height = (e.getBBox().height + 10) + "px";
+                setTimeout(function() {
+                    while (e.firstChild) {
+                        e.removeChild(e.lastChild);
+                    }
+                    markmap.Markmap.create(e, null, r);
+                }, 500);
+            });
+        })(m, svg, root);
+    }
+})();