mkdocs-entangled-plugin 0.3.0__tar.gz → 0.5.0__tar.gz

mkdocs_entangled_plugin-0.5.0/.gitignore

@@ -0,0 +1,6 @@
+site
+.mypy_cache
+.pytest_cache
+__pycache__
+dist
+poetry.lock

{mkdocs_entangled_plugin-0.3.0 → mkdocs_entangled_plugin-0.5.0}/PKG-INFO

@@ -1,21 +1,22 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mkdocs-entangled-plugin
-Version: 0.3.0
+Version: 0.5.0
 Summary: Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects.
-License: Apache 2.0
-Author: Johan Hidding
-Author-email: j.hidding@esciencecenter.nl
-Requires-Python: >=3.11,<4.0
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: entangled-cli[rich] (>=2.0.0a3,<3.0.0)
-Requires-Dist: mkdocs (>=1.4.2,<2.0.0)
+Author-email: Johan Hidding <j.hidding@esciencecenter.nl>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <4,>=3.12
+Requires-Dist: entangled-cli<3,>=2.2
+Requires-Dist: mawk<0.2,>=0.1.7
+Requires-Dist: mkdocs<2,>=1.4.2
 Description-Content-Type: text/markdown
 
 # Welcome to MkDocs Entangled Plugin
 Using this plugin, you can make your Entangled documents look better.
 
+## Examples
+Detailed examples are found in the [entangled/mkdocs-examples repository](https://entangled.github.io/mkdocs-examples).
+
 ## Install
 
 Install this with `pip install mkdocs-entangled-plugin`. To use the entangled plugin, add the following lines to your `mkdocs.yml`:
@@ -30,6 +31,8 @@ markdown_extensions:
       alternate_style: true 
 ```
 
+For more information, see [the documentation](https://entangled.github.io/mkdocs-plugin).
+
 ## Components
 This plugin bundles functionality for literate programming with Entangled.
 
@@ -119,4 +122,3 @@ Build artifacts by specifying a Makefile.
 
 ## License
 Licensed under the Apache-2 license agreement: see LICENSE
-

{mkdocs_entangled_plugin-0.3.0 → mkdocs_entangled_plugin-0.5.0}/README.md

@@ -1,6 +1,9 @@
 # Welcome to MkDocs Entangled Plugin
 Using this plugin, you can make your Entangled documents look better.
 
+## Examples
+Detailed examples are found in the [entangled/mkdocs-examples repository](https://entangled.github.io/mkdocs-examples).
+
 ## Install
 
 Install this with `pip install mkdocs-entangled-plugin`. To use the entangled plugin, add the following lines to your `mkdocs.yml`:
@@ -15,6 +18,8 @@ markdown_extensions:
       alternate_style: true 
 ```
 
+For more information, see [the documentation](https://entangled.github.io/mkdocs-plugin).
+
 ## Components
 This plugin bundles functionality for literate programming with Entangled.
 

mkdocs_entangled_plugin-0.5.0/mkdocs_entangled/on_page_markdown.py

@@ -0,0 +1,137 @@
+from collections.abc import Iterable, Callable
+from functools import partial, reduce
+from pathlib import Path
+from textwrap import indent
+from itertools import chain
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.pages import Page
+from mkdocs.structure.files import Files
+
+from entangled.document import ReferenceMap, Content, PlainText, ReferenceId, CodeBlock, document_to_text
+from entangled.properties import get_attribute, Id, Attribute, Class
+from entangled.hooks import get_hooks
+from entangled.config import config
+from repl_session import read_session
+
+config.read()
+
+# The Entangled config needs to be read before importing the Markdown reader
+# This is very bad I know, and should be fixed in some future version.
+from entangled.markdown_reader import read_markdown_string
+
+
+type ContentFilter = Callable[[ReferenceMap, Content], Iterable[Content]]
+type CodeBlockFilter = Callable[[ReferenceMap, ReferenceId], Iterable[Content]]
+
+
+def codeblock_filter(f: CodeBlockFilter) -> ContentFilter:
+    def _foo(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        match c:
+            case PlainText():
+                return [c]
+            case ReferenceId():
+                return f(rm, c)
+    return _foo
+
+
+def iter_bind[T, U](lst: Iterable[T], f: Callable[[T], Iterable[U]]) -> Iterable[U]:
+    return chain(*map(f, lst))
+
+
+def compose_filter(a: ContentFilter, b: ContentFilter) -> ContentFilter:
+    def _joined(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        return iter_bind(partial(a, rm)(c), partial(b, rm))
+    return _joined
+
+
+def compose_filters(*args: ContentFilter) -> ContentFilter:
+    return reduce(compose_filter, args, lambda _, c: [c])
+
+
+def read_markdown(text: str) -> tuple[ReferenceMap, list[Content]]:
+    hooks = get_hooks()
+    return read_markdown_string(text, hooks=hooks)
+
+
+@codeblock_filter
+def add_title(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """
+    Changes the `open_line` member of a `CodeBlock` to reflect accepted
+    MkDocs syntax, adding a `title` attribute.
+    """
+    codeblock: CodeBlock = reference_map.get_codeblock(r)
+
+    ids = [p.value for p in codeblock.properties if isinstance(p, Id)]
+    classes = [p.value for p in codeblock.properties if isinstance(p, Class)]
+    filenames = [p.value for p in codeblock.properties if isinstance(p, Attribute) and p.key == "file"]
+
+    title = None
+    if len(ids) == 1 and len(filenames) == 1:
+        title = f"#{ids[0]} / file: {filenames[0]}"
+    elif len(ids) == 1:
+        title = f"#{ids[0]}"
+    elif len(filenames) == 1:
+        title = f"file: {filenames[0]}"
+    elif len(ids) > 1 or len(filenames) > 1:
+        title = "error: ambiguous code block title"
+
+    open_line = "```"
+    if classes:
+        language_id = classes[0]
+        open_line += language_id
+
+    if ids or classes or title:
+        open_line += " {"
+
+        if ids:
+            open_line += str(Id(ids[0]))
+
+        for c in classes[1:]:
+            open_line += " " + str(Class(c))
+
+        if title:
+            open_line += " " + str(Attribute("title", title))
+
+        open_line += "}"
+
+    codeblock.open_line = open_line
+    return [r]
+
+
+@codeblock_filter
+def include_repl_output(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """
+    Takes any codeblock that has the `repl` class and append its pre-computed output.
+    """
+    codeblock: CodeBlock = reference_map.get_codeblock(r)
+    if Class("repl") not in codeblock.properties:
+        return [r]
+
+    first: CodeBlock = next(iter(reference_map.by_name(r.name)))
+    session_filename = get_attribute(first.properties, "session")
+    assert session_filename is not None
+    session_path: Path = Path(session_filename)
+    assert session_path.exists()
+    session_output_path: Path = session_path.with_suffix(".out.json")
+    assert session_output_path.exists()
+
+    session = read_session(session_output_path.open("r"))
+    command = session.commands[r.ref_count]
+
+    if not command.output:
+        return [r]
+
+    output: str
+    if command.output_type == "text/plain":
+        output = indent(f"\n``` {{.text .output}}\n{command.output}\n```", codeblock.indent)
+    else:
+        output = indent(f"\n**unknown MIME type: {command.output_type}**", codeblock.indent)
+
+    return [r, PlainText(output)]
+
+
+def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str:
+    reference_map, content = read_markdown(markdown)
+    filtered_content = iter_bind(content, partial(compose_filters(add_title, include_repl_output), reference_map))
+    return document_to_text(reference_map, filtered_content)

{mkdocs_entangled_plugin-0.3.0 → mkdocs_entangled_plugin-0.5.0}/mkdocs_entangled/plugin.py

@@ -1,20 +1,14 @@
-import logging
-import mkdocs
+from typing import override
+from mkdocs.plugins import BasePlugin
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.structure.pages import Page
 from mkdocs.structure.files import Files
 
-from entangled.commands import sync
-from entangled.main import configure
-
 from .on_page_markdown import on_page_markdown
 from .config import EntangledConfig
 
-class EntangledPlugin(mkdocs.plugins.BasePlugin[EntangledConfig]):
-    def on_pre_build(self, config: MkDocsConfig):
-        configure()
-        logging.info("Running `entangled sync`")
-        sync()
-        
+
+class EntangledPlugin(BasePlugin[EntangledConfig]):
+    @override
     def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, files: Files):
         return on_page_markdown(markdown, page=page, config=config, files=files)

mkdocs_entangled_plugin-0.5.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "mkdocs-entangled-plugin"
+version = "0.5.0"
+description = "Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects."
+authors = [{ name = "Johan Hidding", email = "j.hidding@esciencecenter.nl" }]
+requires-python = ">=3.12,<4"
+readme = "README.md"
+license = "Apache-2.0"
+dependencies = [
+    "mkdocs>=1.4.2,<2",
+    "entangled-cli>=2.2,<3",
+    "mawk>=0.1.7,<0.2",
+]
+
+[project.entry-points."mkdocs.plugins"]
+entangled = "mkdocs_entangled:EntangledPlugin"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.2.0,<2",
+    "pytest>=7.3.0,<8",
+    "pytest-mypy>=0.10.3,<0.11",
+    "mkdocs-material>=9.1.6,<10",
+    "pyright>=1.1.406",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["mkdocs_entangled"]
+
+[tool.hatch.build.targets.wheel]
+include = ["mkdocs_entangled"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+addopts = ["--mypy"]
+testpaths = [
+    "test"
+]
+
+[tool.mypy]
+packages = ["mkdocs_entangled"]

mkdocs_entangled_plugin-0.3.0/mkdocs_entangled/mawk.py

@@ -1,100 +0,0 @@
-"""
-μAwk, a tiny awk-like interface in Python
-"""
-
-from typing import Callable, Optional
-from functools import wraps, partial
-import re
-
-
-"""Global counter to sort filters by the order in which they appear
-in a class."""
-_filter_creation_order = 0
-
-
-def match_filter(expr: str, handler: Callable[[re.Match], Optional[list[str]]], inp: str) -> Optional[list[str]]:
-    if m := re.match(expr, inp):
-        return handler(m)
-    return None
-
-
-def on_match(expr: str):
-    """Decorator for doing search-and-replace based on a given regex.
-    
-    The inner function should take as argument a `re.Match` object
-    and return a list of strings. The resulting decorated function
-    then becomes a function from string to list of strings.
-    
-    If the input doesn't match the given regex, the original string
-    is returned.
-    
-    The inner function may still decide to do nothing by returning None.
-    
-    To erase the matched input return the empty list.
-
-    This decorator also works on class methods. It is then assumed that
-    the method has signature `(self, m: re.Match)`.
-    """
-    def _decorator(f):
-        global _filter_creation_order
-        method = len(f.__qualname__.split('.')) > 1
-        if method:
-            @wraps(f)
-            def _impl(self, inp):
-                return match_filter(expr, partial(f, self), inp)
-            _impl._is_rule = _filter_creation_order  # add tag to method
-            _filter_creation_order += 1
-            return _impl
-        else:
-            return wraps(f)(partial(match_filter, expr, f))
-    return _decorator
-
-
-def always(f):
-    """Suppose you have a rule with `@on_match(r".*")`, then it is better
-    not to run the regex machinery at all and just pass on the string.
-    In that case it is better to use `@always`."""
-    global _filter_creation_order
-    method = len(f.__qualname__.split('.')) > 1
-    if method:
-        f._is_rule = _filter_creation_order  # add tag to method
-        _filter_creation_order += 1
-        return f
-    else:
-        return f
-
-
-Rule = Callable[[str], list[str]]
-
-
-def run(rules: list[Rule], inp: str, exclusive=True) -> str:
-    """Takes a list of rules, being function from `str` to `list[str]`.
-    The input string is split into lines, after which each line is fed
-    through the list of rules. All the results are colected into a list
-    of strings and then joined by newline.
-    """
-    lines = inp.splitlines()
-    result = []
-    for l in lines:
-        for r in rules:
-            v = r(l)
-            if v is not None:
-                result.extend(v)
-                if exclusive:
-                    break
-        else:
-            result.append(l)
-    return "\n".join(result)
-
-
-class RuleSet:
-    """To be used as a base class for classes that contain `on_match`
-    decorated methods."""
-    def list_rules(self):
-        members = (getattr(self, m) for m in dir(self) if m[0] != '_')
-        rules = [m for m in members if hasattr(m, '_is_rule')]
-        return sorted(rules, key=lambda r: r._is_rule)
-
-    def run(self, inp: str, exclusive=True) -> str:
-        """Runs all rules in the class on input."""
-        return run(self.list_rules(), inp, exclusive)

mkdocs_entangled_plugin-0.3.0/mkdocs_entangled/on_page_markdown.py

@@ -1,64 +0,0 @@
-from typing import Optional
-from dataclasses import dataclass
-import re
-
-from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.structure.pages import Page
-from mkdocs.structure.files import Files
-
-from .properties import read_properties, Id, Attribute
-from . import mawk
-
-
-@dataclass
-class EntangledFilter(mawk.RuleSet):
-    add_title: bool = True
-    _ignore: bool = False
-
-    @mawk.on_match(r"~~~markdown")
-    def start_ignore(self, m):
-        self._ignore = True
-        return [m[0]]
-    
-    @mawk.on_match(r"~~~")
-    def stop_ignore(self, m):
-        self._ignore = False
-        return [m[0]]
-
-    @mawk.on_match(r"(\s*)``` *\{([^}]*)\}")
-    def open_code_block(self, m: re.Match) -> Optional[list[str]]:
-        if self._ignore:
-            return None
-
-        indent = m[1]
-        props = list(read_properties(m[2]))
-        
-        ids = [p.value for p in props if isinstance(p, Id)]
-        filenames = [p.value for p in props if isinstance(p, Attribute) and p.key == "file"]
-
-        if self.add_title:
-            title = None
-            if len(ids) == 1 and len(filenames) == 1:
-                title = f"#{ids[0]} / file: {filenames[0]}"
-            elif len(ids) == 1:
-                title = f"#{ids[0]}"
-            elif len(filenames) == 1:
-                title = f"file: {filenames[0]}"
-            elif len(ids) > 1 or len(filenames) > 1:
-                title = f"error: ambiguous code block title"
-
-            if title is not None:
-                props.append(Attribute("title", title))
-        
-        prop_str = " ".join(str(p) for p in props)
-        return [f"{indent}``` {{{prop_str}}}"]
-
-    @mawk.on_match(r"\s*```\s*$")
-    def close_code_block(self, m: re.Match) -> Optional[list[str]]:
-        return None
-
-
-def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str:
-    result = EntangledFilter().run(markdown)
-    return result
-

mkdocs_entangled_plugin-0.3.0/mkdocs_entangled/properties.py

@@ -1,124 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Optional, Protocol, TypeVar, Generic, Any, Sequence, Union
-import re
-
-
-T = TypeVar("T")
-T_co = TypeVar("T_co", covariant=True)
-
-class Parser(Protocol[T_co]):
-    def read(self, inp: str) -> Optional[tuple[T_co, str]]:
-        ...
-
-@dataclass
-class Id:
-    value: str
-
-    def __str__(self):
-        return f"#{self.value}"
-
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Id, str]]:
-        if m := re.match("#([^ {}]+)", inp):
-            return Id(m[1]), inp[m.end():]
-        return None
-
-
-@dataclass
-class Class:
-    value: str
-
-    def __str__(self):
-        return f".{self.value}"
-
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Class, str]]:
-        if m := re.match("\\.([^ {}]+)", inp):
-            return Class(m[1]), inp[m.end():]
-        return None
-
-
-@dataclass
-class Attribute:
-    key: str
-    value: str
-
-    def __str__(self):
-        return f"{self.key}=\"{self.value}\""
-    
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Attribute, str]]:
-        if m := re.match("([^ {}]+) *= *([^ {}\"]+)", inp):
-            return Attribute(m[1], m[2]), inp[m.end():]
-        if m := re.match("([^ {}]+) *= *\"([^\"]*)\"", inp):
-            return Attribute(m[1], m[2]), inp[m.end():]
-        return None
-
-
-Property = Union[Attribute, Class, Id]
-
-@dataclass
-class Choice(Generic[T]):
-    options: Sequence[Parser[T]]
-
-    def read(self, inp: str) -> Optional[tuple[T, str]]:
-        for o in self.options:
-            rv = o.read(inp)
-            if rv is None:
-                continue
-            else:
-                return rv
-        return None
-
-
-@dataclass
-class Many(Generic[T]):
-    parser: Parser[T]
-
-    def read(self, inp: str) -> tuple[list[T], str]:
-        result: list[T] = []
-        while True:
-            rv = self.parser.read(inp)
-            if rv is None:
-                return result, inp
-            else:
-                value, rest = rv
-                result.append(value)
-                inp = rest
-
-
-@dataclass
-class Skip:
-    what: str
-
-    def read(self, inp: str) -> Optional[tuple[None, str]]:
-        if m := re.match(self.what, inp):
-            return None, inp[m.end():]
-        return None
-
-
-@dataclass
-class Last(Generic[T]):
-    first: Parser[Any]
-    second: Parser[T]
-
-    def read(self, inp: str) -> Optional[tuple[T, str]]:
-        rv = self.first.read(inp)
-        if rv is None:
-            return None
-        else:
-            _, rest = rv
-            return self.second.read(rest)
-
-
-def tokenize(p: Parser[T]) -> Parser[T]:
-    return Last(Skip(" *"), p)
-
-
-def read_properties(inp: str) -> list[Property]:
-    # Explicit typing is needed to convince MyPy of correctness
-    parsers: list[Parser[Property]] = [Id, Class, Attribute]
-    result, _ = Many(tokenize(Choice(parsers))).read(inp) 
-    return result

mkdocs_entangled_plugin-0.3.0/pyproject.toml

@@ -1,39 +0,0 @@
-[tool.poetry]
-name = "mkdocs-entangled-plugin"
-version = "0.3.0"
-description = "Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects."
-readme = "README.md"
-authors = ["Johan Hidding <j.hidding@esciencecenter.nl>"]
-license = "Apache 2.0"
-packages = [
-    { include = "mkdocs_entangled" }
-]
-
-[tool.poetry.plugins."mkdocs.plugins"]
-entangled = "mkdocs_entangled:EntangledPlugin"
-
-[tool.poetry.dependencies]
-python = "^3.11"
-mkdocs = "^1.4.2"
-# entangled-cli = {path = "../entangled.py", extras = ["rich"], develop = true}
-entangled-cli = {extras = ["rich"], version = "^2.0.0a3"}
-
-[tool.poetry.dev-dependencies]
-mypy = "^1.2.0"
-pytest = "^7.3.0"
-pytest-mypy = "^0.10.3"
-mkdocs-material = "^9.1.6"
-twine = "^4.0.2"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.pytest.ini_options]
-addopts = ["--mypy"]
-testpaths = [
-    "test"
-]
-
-[tool.mypy]
-packages = ["mkdocs_entangled"]