Bundle custom plugins in this repo

plugins/mkdocs-uktre-glossary-plugin/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 Tim Vink
+Copyright (c) 2025 UKTRE
+
+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.

plugins/mkdocs-uktre-glossary-plugin/README.md

@@ -0,0 +1,3 @@
+# mkdocs-uktre-glossary-plugin
+
+An [MkDocs](https://www.mkdocs.org/) plugin based on [mkdocs-table-reader-plugin](https://github.com/timvink/mkdocs-table-reader-plugin) to convert the UK TRE glossary from YAML to HTML.

plugins/mkdocs-uktre-glossary-plugin/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=70.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project.entry-points."mkdocs.plugins"]
+"uktre-glossary" = "mkdocs_uktre_glossary_plugin.plugin:GlossaryPlugin"
+
+[project]
+name="mkdocs_uktre_glossary_plugin"
+keywords = ["mkdocs", "plugin"]
+authors = [
+    {name = "UKTRE"},
+]
+license = { text = "MIT" }
+
+description="MkDocs plugin to generate UKTRE glossary"
+readme = { file = "README.md", content-type = "text/markdown" }
+
+requires-python=">=3.11"
+
+classifiers=[
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+
+dynamic = ["version"]
+dependencies = [
+    "mkdocs>=1.6.1",
+    "pandas>=2.2.3",
+    "pyyaml>=6.0.2",
+    "tabulate>=0.9.0",
+    # We're hooking in to the internals of this plugin, so pin exactly
+    "mkdocs-table-reader-plugin==3.1.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/TODO/TODO"
+
+[tool.setuptools.dynamic]
+version = {attr = "mkdocs_uktre_glossary_plugin.__version__"}

plugins/mkdocs-uktre-glossary-plugin/src/mkdocs_uktre_glossary_plugin/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.1.0"

plugins/mkdocs-uktre-glossary-plugin/src/mkdocs_uktre_glossary_plugin/plugin.py

@@ -0,0 +1,41 @@
+from mkdocs.config import config_options
+from mkdocs.plugins import get_plugin_logger
+from mkdocs_table_reader_plugin.plugin import TableReaderPlugin
+
+from .readers import READERS
+
+logger = get_plugin_logger("uktre-glossary")
+
+
+class GlossaryPlugin(TableReaderPlugin):
+    config_scheme = (
+        ("data_path", config_options.Type(str, default=".")),
+        ("allow_missing_files", config_options.Type(bool, default=False)),
+        (
+            "select_readers",
+            config_options.ListOfItems(
+                config_options.Choice(list(READERS.keys())),
+                default=list(READERS.keys()),
+            ),
+        ),
+    )
+
+    def on_config(self, config, **kwargs):
+        """
+        See https://www.mkdocs.org/user-guide/plugins/#on_config.
+
+        Args:
+            config
+
+        Returns:
+            Config
+        """
+
+        self.readers = {
+            reader: READERS[reader].set_config_context(
+                mkdocs_config=config, plugin_config=self.config
+            )
+            for reader in self.config.get("select_readers")
+            if reader in self.config.get("select_readers", [])
+        }
+        self.external_jinja_engine = False

plugins/mkdocs-uktre-glossary-plugin/src/mkdocs_uktre_glossary_plugin/readers.py

@@ -0,0 +1,119 @@
+import logging
+
+from html import escape
+from markdown import markdown
+import pandas as pd
+from textwrap import dedent
+import re
+import yaml
+
+from mkdocs_table_reader_plugin.markdown import convert_to_md_table
+from mkdocs_table_reader_plugin.readers import ParseArgs
+from mkdocs_table_reader_plugin.utils import kwargs_in_func, kwargs_not_in_func
+
+logger = logging.getLogger("mkdocs.plugins")
+
+
+
+def _slugify(s: str):
+    return re.sub(r"\W", "-", s.lower())
+
+def link_urls(s: str):
+    trailing_punctuation = re.escape(".,!?)]}>'\"")
+    s = re.sub(rf"(https?://[\S]+[^{trailing_punctuation}])", r"[\1](\1)", s)
+    return s
+
+def _crossref_terms(text):
+    # Find [...] but not [...](...)
+    matches = re.findall(r"(\[[^]]+\])([^(]|$)", text)
+    # Get the first capture group
+    crossrefs = set(m[0] for m in matches)
+
+    for crossref in crossrefs:
+        target_term = crossref[1:-1]
+        link_target = "#term-" + _slugify(target_term)
+        link_md = f"[{target_term}]({link_target})"
+        text = text.replace(crossref, link_md)
+    return text
+
+
+def to_glossary_html(df, **kwargs):
+    """
+    df.to_markdown() escapes some HTML, so create a HTML table ourselves
+    """
+    if kwargs:
+        raise ValueError(f"Unsupported kwargs: {kwargs}")
+
+    out = """
+    <table>
+        <tr>
+            <th>Term</th>
+            <th>Tags</th>
+            <th>Definition</th>
+        </tr>
+    """
+    for row in df.itertuples(index=False):
+        anchor = "term-" + _slugify(row.term)
+        crossreferenced = _crossref_terms(link_urls(row.definition))
+        definition = markdown(escape(crossreferenced))
+
+        row = f"""
+        <tr>
+            <td id="{anchor}"><a href="#{anchor}">{escape(row.term)}</a></td>
+            <td>{escape(", ".join(row.tags))}</td>
+            <td>{markdown(definition)}</td>
+        </tr>
+        """
+        out += row
+
+    out += """
+    </table>
+    """
+
+    stripped = "\n".join(line.strip() for line in out.splitlines() if line.strip())
+    return stripped
+
+
+@ParseArgs
+def read_csv(*args, **kwargs) -> str:
+    read_kwargs = kwargs_in_func(kwargs, pd.read_csv)
+    df = pd.read_csv(*args, **read_kwargs)
+
+    markdown_kwargs = kwargs_not_in_func(kwargs, pd.read_csv)
+    return to_glossary_html(df, **markdown_kwargs)
+
+
+@ParseArgs
+def read_json(*args, **kwargs) -> str:
+    read_kwargs = kwargs_in_func(kwargs, pd.read_json)
+    df = pd.read_json(*args, **read_kwargs)
+
+    markdown_kwargs = kwargs_not_in_func(kwargs, pd.read_json)
+    return to_glossary_html(df, **markdown_kwargs)
+
+
+@ParseArgs
+def read_excel(*args, **kwargs) -> str:
+    read_kwargs = kwargs_in_func(kwargs, pd.read_excel)
+    df = pd.read_excel(*args, **read_kwargs)
+
+    markdown_kwargs = kwargs_not_in_func(kwargs, pd.read_excel)
+    return to_glossary_html(df, **markdown_kwargs)
+
+
+@ParseArgs
+def read_yaml(*args, **kwargs) -> str:
+    json_kwargs = kwargs_in_func(kwargs, pd.json_normalize)
+    with open(args[0]) as f:
+        df = pd.json_normalize(yaml.safe_load(f), **json_kwargs)
+
+    markdown_kwargs = kwargs_not_in_func(kwargs, pd.json_normalize)
+    return to_glossary_html(df, **markdown_kwargs)
+
+
+READERS = {
+    "read_csv": read_csv,
+    "read_excel": read_excel,
+    "read_yaml": read_yaml,
+    "read_json": read_json,
+}

requirements.in

@@ -1,3 +1,3 @@
-git+https://github.com/manics/mkdocs-uktre-glossary-plugin.git@a2dec8e5045c0b51d7ce44a1f302f5fc9564e687
+file:plugins/mkdocs-uktre-glossary-plugin#egg=mkdocs-uktre-glossary-plugin
 mkdocs
 mkdocs-material

requirements.txt

@@ -51,7 +51,7 @@ mkdocs-material-extensions==1.3.1
     # via mkdocs-material
 mkdocs-table-reader-plugin==3.1.0
     # via mkdocs-uktre-glossary-plugin
-mkdocs-uktre-glossary-plugin @ git+https://github.com/manics/mkdocs-uktre-glossary-plugin.git@a2dec8e5045c0b51d7ce44a1f302f5fc9564e687
+file:plugins/mkdocs-uktre-glossary-plugin#egg=mkdocs-uktre-glossary-plugin
     # via -r requirements.in
 numpy==2.2.4
     # via pandas