uEdition 0.8.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

uedition/ext/language_switcher.js

@@ -1,4 +1,4 @@
-(function() {
+(function () {
     async function setup() {
         try {
             let buttonContainer = document.querySelector('.article-header-buttons');
@@ -39,7 +39,7 @@
                     link.classList.add('fw-bold');
                 }
                 link.innerHTML = langConfig.label;
-                link.setAttribute('href', DOCUMENTATION_OPTIONS.URL_ROOT + '../' + langConfig.path + '/' + DOCUMENTATION_OPTIONS.pagename + DOCUMENTATION_OPTIONS.LINK_SUFFIX);
+                link.setAttribute('href', document.querySelector("html").getAttribute("data-content_root") + '../' + langConfig.path + '/' + DOCUMENTATION_OPTIONS.pagename + DOCUMENTATION_OPTIONS.LINK_SUFFIX);
 
                 item.append(link);
                 menu.append(item);
@@ -50,7 +50,7 @@
             container.append(button);
             container.append(menu);
             buttonContainer.prepend(container);
-        } catch(e) {
+        } catch (e) {
             console.error(e);
         }
     }

uedition/ext/language_switcher.py

@@ -3,25 +3,23 @@
 # SPDX-License-Identifier: MIT
 """The Language Switcher extension."""
 import json
-
-from importlib.resources import files, as_file
+from importlib.resources import as_file, files
 from os import path
+
 from sphinx.application import Sphinx
 from sphinx.util.fileutil import copy_asset_file
 
-from ..settings import settings
+from uedition.settings import settings
 
 
 def add_language_switcher(app: Sphinx) -> None:
     """Add the language switcher in-line and file JavaScript."""
-    app.add_js_file(
-        None, body=f"""DOCUMENTATION_OPTIONS.UEDITION = {json.dumps(settings)}"""
-    )
+    app.add_js_file(None, body=f"""DOCUMENTATION_OPTIONS.UEDITION = {json.dumps(settings)}""")
     app.add_js_file("language_switcher.js")
     app.add_css_file("language_switcher.css")
 
 
-def copy_custom_files(app: Sphinx, exc: bool) -> None:
+def copy_custom_files(app: Sphinx, exc: bool) -> None:  # noqa: FBT001
     """Copy the language_switcher.js file from the package."""
     if app.builder.format == "html" and not exc:
         staticdir = path.join(app.builder.outdir, "_static")
@@ -34,5 +32,6 @@ def copy_custom_files(app: Sphinx, exc: bool) -> None:
 
 def setup(app: Sphinx) -> None:
     """Set up the Language switcher extension."""
-    app.connect("builder-inited", add_language_switcher)
-    app.connect("build-finished", copy_custom_files)
+    if len(settings["languages"]) > 1:
+        app.connect("builder-inited", add_language_switcher)
+        app.connect("build-finished", copy_custom_files)

uedition/ext/tei/__init__.py

@@ -0,0 +1,32 @@
+"""TEI extension for Sphinx."""
+
+from importlib.resources import as_file, files
+from os import path
+
+from sphinx.application import Sphinx
+from sphinx.util.fileutil import copy_asset_file
+
+from uedition.ext.tei import parser
+from uedition.settings import settings
+
+
+def add_language_switcher(app: Sphinx) -> None:
+    """Add the language switcher in-line and file JavaScript."""
+    app.add_js_file("tei_download.js")
+
+
+def copy_custom_files(app: Sphinx, exc: bool) -> None:  # noqa: FBT001
+    """Copy the language_switcher.js file from the package."""
+    if app.builder.format == "html" and not exc:
+        staticdir = path.join(app.builder.outdir, "_static")
+        ext_pkg = files("uedition.ext.tei")
+        with as_file(ext_pkg / "tei_download.js") as js_file:
+            copy_asset_file(str(js_file), staticdir)
+
+
+def setup(app: Sphinx) -> None:
+    """Set up the TEI Sphinx extension."""
+    parser.setup(app)
+    if settings["output"]["tei"]:
+        app.connect("builder-inited", add_language_switcher)
+        app.connect("build-finished", copy_custom_files)

uedition/ext/tei/builder.py

@@ -0,0 +1,297 @@
+"""Builder for generating TEI XML outputs."""
+
+import logging
+import os
+import xml.sax.saxutils
+from collections.abc import Iterator
+
+import sphinx
+import sphinx_jupyterbook_latex
+from docutils import nodes
+from docutils.io import StringOutput
+from sphinx.application import Sphinx
+from sphinx.builders.xml import XMLBuilder
+from sphinx.locale import __
+from sphinx.util.osutil import ensuredir, os_path
+from sphinx.writers.xml import XMLWriter
+
+logger = logging.getLogger(__name__)
+
+MAPPINGS = [
+    {"cls": nodes.document, "tagname": "body", "type": "block"},
+    {"cls": nodes.section, "tagname": "div", "type": "block"},
+    {"cls": nodes.paragraph, "tagname": "p", "type": "block"},
+    {"cls": nodes.title, "tagname": "head", "type": "block"},
+    {"cls": nodes.bullet_list, "tagname": "list", "type": "block", "attrs": [{"target": "rend", "value": "bulleted"}]},
+    {
+        "cls": nodes.enumerated_list,
+        "tagname": "list",
+        "type": "block",
+        "attrs": [{"target": "rend", "value": "numbered"}],
+    },
+    {"cls": nodes.list_item, "tagname": "item", "type": "block"},
+    {
+        "cls": nodes.literal_block,
+        "tagname": "div",
+        "type": "block",
+        "attrs": [{"target": "type", "value": "literal-block"}, {"source": "language", "target": "subtype"}],
+    },
+    {"cls": nodes.compound, "tagname": "div", "type": "block"},
+    {"cls": sphinx.addnodes.toctree},
+    {
+        "cls": nodes.footnote,
+        "tagname": "note",
+        "type": "block",
+        "attrs": [
+            {"target": "type", "value": "footnote"},
+            {"target": "target", "source": "backrefs", "format": "#{value}", "join": " "},
+        ],
+    },
+    {"cls": sphinx_jupyterbook_latex.nodes.HiddenCellNode},
+    {
+        "cls": nodes.transition,
+        "tagname": "div",
+        "type": "empty",
+        "attrs": [{"target": "rend", "value": "horizontal-line"}],
+    },
+    {"cls": nodes.inline, "tagname": "hi", "type": "inline"},
+    {"cls": nodes.literal, "tagname": "hi", "type": "inline"},
+    {"cls": nodes.strong, "tagname": "hi", "type": "inline", "attrs": [{"target": "rend", "value": "bold"}]},
+    {"cls": nodes.emphasis, "tagname": "hi", "type": "inline", "attrs": [{"target": "rend", "value": "italic"}]},
+    {"cls": nodes.label, "tagname": "label", "type": "inline"},
+    {
+        "cls": nodes.reference,
+        "tagname": "ref",
+        "type": "inline",
+        "attrs": [{"source": "refuri", "target": "target"}],
+    },
+    {
+        "cls": nodes.footnote_reference,
+        "tagname": "ref",
+        "type": "inline",
+        "attrs": [{"source": "refid", "target": "target", "format": "#{value}"}],
+    },
+]
+
+
+class TEITranslator(nodes.GenericNodeVisitor):
+    """Translator for converting a Docutils document to TEI XML."""
+
+    def __init__(self, document: nodes.document) -> None:
+        """Initialise the translator."""
+        nodes.NodeVisitor.__init__(self, document)
+
+        # Reporter
+        self.warn = self.document.reporter.warning
+        self.error = self.document.reporter.error
+
+        # Settings
+        self.settings = settings = document.settings
+        self.indent = self.newline = ""
+        if settings.newlines:
+            self.newline = "\n"
+        if settings.indents:
+            self.newline = "\n"
+            self.indent = "  "
+        self.level = 0
+        self.inline_level = 0
+        self.fixed_level = 0
+
+        self.output = []
+        if settings.xml_declaration:
+            self.output.append(f'<?xml version="1.0" encoding="{settings.output_encoding}"?>\n')
+
+    def rule_for_node(self, node: nodes.Element) -> dict:
+        """Get the transformation rule for a node."""
+        for rule in MAPPINGS:
+            if isinstance(node, rule["cls"]):
+                return rule
+        self.warn(f"Unknown node {node.__class__.__module__}.{node.__class__.__qualname__} ({node.attlist()})")
+        return {"tagname": "div", "type": "block"}
+
+    def default_visit(self, node: nodes.Element) -> None:
+        """Visit a generic node."""
+        rule = self.rule_for_node(node)
+        # Skip the node if it has no associated TEI "tagname"
+        if "tagname" not in rule:
+            raise nodes.SkipNode
+        # Special handling for the root document, which needs the TEI structure wrapping
+        if isinstance(node, nodes.document):
+            self.output.append('<tei:TEI xmlns:tei="http://www.tei-c.org/ns/1.0">\n')
+            self.output.append("  <tei:text>\n")
+            self.level += 2
+        self.output.append(self.indent * self.level)
+        self.output.append(f"<tei:{rule['tagname']}")
+        # Process the default "ids" and "classes" list
+        output_attrs = {}
+        for attr in node.attlist():
+            if attr[0] == "ids":
+                output_attrs["xml:id"] = attr[1][0]
+                # self.output.append(f' xml:id={xml.sax.saxutils.quoteattr()}')
+            elif attr[0] == "classes":
+                if isinstance(attr[1], list):
+                    output_attrs["rend"] = " ".join(attr[1])
+                else:
+                    output_attrs["rend"] = str(attr[1])
+        # Process all configured attributes
+        if "attrs" in rule:
+            for attr_rule in rule["attrs"]:
+                if "value" in attr_rule:
+                    output_attrs[attr_rule["target"]] = attr_rule["value"]
+                for attr in node.attlist():
+                    if "source" in attr_rule and attr[0] == attr_rule["source"]:
+                        output_attrs[attr_rule["target"]] = attr[1]
+                if attr_rule["target"] in output_attrs and isinstance(output_attrs[attr_rule["target"]], list):
+                    joiner = attr_rule["join"] if "join" in attr_rule else " "
+                    if "format" in attr_rule:
+                        output_attrs[attr_rule["target"]] = joiner.join(
+                            [attr_rule["format"].replace("{value}", v) for v in output_attrs[attr_rule["target"]]]
+                        )
+                    else:
+                        output_attrs[attr_rule["target"]] = joiner.join(output_attrs[attr_rule["target"]])
+                elif "format" in attr_rule:
+                    output_attrs[attr_rule["target"]] = attr_rule["format"].replace(
+                        "{value}", output_attrs[attr_rule["target"]]
+                    )
+        # Write the sorted attributes
+        sorted_output_attrs = list(output_attrs.items())
+        sorted_output_attrs.sort()
+        for name, value in sorted_output_attrs:
+            self.output.append(f" {name}={xml.sax.saxutils.quoteattr(value)}")
+        if rule["type"] == "empty":
+            self.output.append("/>")
+            self.output.append(self.newline)
+            raise nodes.SkipNode
+        else:
+            self.output.append(">")
+        # Update the indentation levels
+        self.level += 1
+        if isinstance(node, nodes.FixedTextElement):
+            self.fixed_level += 1
+        if rule["type"] == "inline":
+            self.inline_level += 1
+        elif rule["type"] == "block":
+            self.output.append(self.newline)
+
+    def default_departure(self, node: nodes.Element) -> None:
+        """Depart a generic node."""
+        rule = self.rule_for_node(node)
+        self.level -= 1
+        # Only indent if we are not inside an inline element
+        if self.inline_level == 0:
+            self.output.append(self.indent * self.level)
+        self.output.append(f"</tei:{rule['tagname']}>")
+        # Update the indentation levels
+        if isinstance(node, nodes.FixedTextElement):
+            self.fixed_level -= 1
+        self.output.append(self.newline)
+        if rule["type"] == "inline":
+            self.inline_level -= 1
+        if isinstance(node, nodes.document):
+            self.output.append("  </tei:text>\n")
+            self.output.append("</tei:TEI>")
+            self.level -= 2
+
+    # specific visit and depart methods
+    # ---------------------------------
+
+    def visit_Text(self, node: nodes.TextElement) -> None:  # noqa: N802
+        """Output the Text node content."""
+        text = xml.sax.saxutils.escape(node.astext())
+        if self.inline_level > 0:
+            if self.fixed_level > 0:
+                self.output.append(text)
+            else:
+                self.output.append(text)
+        else:
+            self.output.append(f"{self.indent*self.level}<tei:span>{text}</tei:span>\n")
+
+    def depart_Text(self, node: nodes.TextElement) -> None:  # noqa: N802
+        """Unused."""
+        pass
+
+    def visit_raw(self, node: nodes.raw) -> None:
+        """Visit a raw node."""
+        if "tei" not in node.get("format", "").split():
+            raise nodes.SkipNode
+        xml_string = node.astext()
+        self.output.append(xml_string)
+        raise nodes.SkipNode
+
+
+class TEIBuilder(XMLBuilder):
+    """Builds TEI representations of the μEdition."""
+
+    name = "tei"
+    format = "tei"
+    epilog = __("The TEI files are in %(outdir)s.")
+
+    out_suffix = ".tei"
+    allow_parallel = True
+
+    _writer_class: type[XMLWriter] = XMLWriter
+    writer: XMLWriter
+    default_translator_class = TEITranslator
+
+    def get_outdated_docs(self) -> Iterator[str]:
+        """Determine the list of outdated documents."""
+        for docname in self.env.found_docs:
+            if docname not in self.env.all_docs:
+                yield docname
+                continue
+            targetname = os.path.join(self.outdir, docname + self.out_suffix)
+            try:
+                targetmtime = os.path.getmtime(targetname)
+            except Exception:
+                targetmtime = 0
+            try:
+                srcmtime = os.path.getmtime(self.env.doc2path(docname))
+                if srcmtime > targetmtime:
+                    yield docname
+            except OSError:
+                # source doesn't exist anymore
+                pass
+
+    def get_target_uri(self, docname: str, typ: str | None = None) -> str:  # noqa: ARG002
+        """Return the `docname` as the target_uri."""
+        return docname
+
+    def prepare_writing(self, docnames: set[str]) -> None:  # noqa: ARG002
+        """Prepare for writing."""
+        self.writer = self._writer_class(self)
+
+    def write_doc(self, docname: str, doctree: nodes.Node) -> None:
+        """Write a single document."""
+        # work around multiple string % tuple issues in docutils;
+        # replace tuples in attribute values with lists
+        doctree = doctree.deepcopy()
+        for domain in self.env.domains.values():
+            xmlns = "xmlns:" + domain.name
+            doctree[xmlns] = "https://www.sphinx-doc.org/"  # type: ignore
+        for node in doctree.findall(nodes.Element):
+            for att, value in node.attributes.items():
+                if isinstance(value, tuple):
+                    node.attributes[att] = list(value)
+                value = node.attributes[att]  # noqa: PLW2901
+                if isinstance(value, list):
+                    for i, val in enumerate(value):
+                        if isinstance(val, tuple):
+                            value[i] = list(val)
+        destination = StringOutput(encoding="utf-8")
+        self.writer.write(doctree, destination)
+        outfilename = os.path.join(self.outdir, os_path(docname) + self.out_suffix)
+        ensuredir(os.path.dirname(outfilename))
+        try:
+            with open(outfilename, "w", encoding="utf-8") as f:
+                f.write(self.writer.output)
+        except OSError as err:
+            logger.warning(__("error writing file %s: %s"), outfilename, err)
+
+    def finish(self) -> None:
+        """Unused."""
+        pass
+
+
+def setup(app: Sphinx) -> None:
+    """Set up the TEI Sphinx extension."""
+    app.add_builder(TEIBuilder)

uedition/ext/{tei.py → tei/parser.py}

@@ -8,7 +8,6 @@ from sphinx.application import Sphinx
 from sphinx.parsers import Parser as SphinxParser
 from sphinx.writers.html import HTMLWriter
 
-
 namespaces = {"tei": "http://www.tei-c.org/ns/1.0"}
 
 
@@ -52,7 +51,7 @@ class TEIParser(SphinxParser):
         :param document: The root docutils node to add AST elements to
         :type document: :class:`~docutils.nodes.document`
         """
-        root = etree.fromstring(inputstring.encode("UTF-8"))
+        root = etree.fromstring(inputstring.encode("UTF-8"))  # noqa: S320
         title = root.xpath(
             "string(/tei:TEI/tei:teiHeader/tei:fileDesc/tei:titleStmt/tei:title)",
             namespaces=namespaces,
@@ -86,9 +85,7 @@ class TEIParser(SphinxParser):
                             self._parse_list_field(fields, field, root)
         document.append(doc_section)
 
-    def _walk_tree(
-        self: "TEIParser", node: etree.Element, parent: nodes.Element, rules: list
-    ) -> None:
+    def _walk_tree(self: "TEIParser", node: etree.Element, parent: nodes.Element, rules: list) -> None:
         """Walk the XML tree and create the appropriate AST nodes.
 
         Uses the mapping rules defined in :mod:`~uEdition.extensions.config` to determine what to
@@ -96,9 +93,7 @@ class TEIParser(SphinxParser):
         """
         is_leaf = len(node) == 0
         text_only_in_leaf_nodes = (
-            self.config.uEdition["tei"]["text_only_in_leaf_nodes"]
-            if "tei" in self.config.uEdition
-            else False
+            self.config.uEdition["tei"]["text_only_in_leaf_nodes"] if "tei" in self.config.uEdition else False
         )
         attributes = {}
         # Get the first matching rule for the current node
@@ -107,7 +102,7 @@ class TEIParser(SphinxParser):
         for key, value in node.attrib.items():
             # Always strip the namespace from the `id` attribute
             if key == "{http://www.w3.org/XML/1998/namespace}id":
-                key = "id"
+                key = "id"  # noqa: PLW2901
             if rule and "attributes" in rule:
                 processed = False
                 for attr_rule in rule["attributes"]:
@@ -120,7 +115,7 @@ class TEIParser(SphinxParser):
                             processed = True
                     elif attr_rule["action"] == "set":
                         if key == attr_rule["attr"]:
-                            value = attr_rule["value"]
+                            value = attr_rule["value"]  # noqa: PLW2901
                 # if the attribute did not match any attribute transform
                 if not processed:
                     # The id attribute is always output as is, all other attributes are prefixed with `data-`
@@ -128,7 +123,7 @@ class TEIParser(SphinxParser):
                         attributes["id"] = value
                     else:
                         attributes[f"data-{key}"] = value
-            else:
+            else:  # noqa: PLR5501
                 # The id attribute is always output as is, all other attributes are prefixed with `data-`
                 if key == "id":
                     attributes["id"] = value
@@ -143,15 +138,11 @@ class TEIParser(SphinxParser):
         parent.append(new_element)
         if rule is not None and "text" in rule and rule["text"]:
             # If there is a `text` key in the rule, use that to set the text
-            if (
-                rule["text"]["action"] == "from-attribute"
-                and rule["text"]["attr"] in node.attrib
-            ):
+            if rule["text"]["action"] == "from-attribute" and rule["text"]["attr"] in node.attrib:
                 new_element.append(nodes.Text(node.attrib[rule["text"]["attr"]]))
-        else:
-            if node.text and (is_leaf or not text_only_in_leaf_nodes):
-                # Only create text content if there is text and we either are in a leaf node or are adding all text
-                new_element.append(nodes.Text(node.text))
+        elif node.text and (is_leaf or not text_only_in_leaf_nodes):
+            # Only create text content if there is text and we either are in a leaf node or are adding all text
+            new_element.append(nodes.Text(node.text))
         # Process any children
         for child in node:
             self._walk_tree(child, new_element, rules)
@@ -159,9 +150,7 @@ class TEIParser(SphinxParser):
         if node.tail and not text_only_in_leaf_nodes:
             parent.append(nodes.Text(node.tail))
 
-    def _wrap_sections(
-        self: "TEIParser", section: nodes.Element, tmp: nodes.Element
-    ) -> None:
+    def _wrap_sections(self: "TEIParser", section: nodes.Element, tmp: nodes.Element) -> None:
         """Ensure that sections are correctly wrapped."""
         section_stack = [(0, section)]
         for node in tmp.children:
@@ -203,9 +192,7 @@ class TEIParser(SphinxParser):
                 if not in_heading:
                     section_stack[-1][1].append(node)
 
-    def _rule_for_node(
-        self: "TEIParser", node: etree.Element, rules: list[dict]
-    ) -> dict:
+    def _rule_for_node(self: "TEIParser", node: etree.Element, rules: list[dict]) -> dict:
         """Determine the first matching mapping rule for the node from the configured rules."""
         tei_tag = node.tag
         for rule in rules:
@@ -213,10 +200,7 @@ class TEIParser(SphinxParser):
                 if "attributes" in rule["selector"]:
                     attr_match = True
                     for attr_rule in rule["selector"]["attributes"]:
-                        if (
-                            attr_rule["attr"] not in node.attrib
-                            or node.attrib[attr_rule["attr"]] != attr_rule["value"]
-                        ):
+                        if attr_rule["attr"] not in node.attrib or node.attrib[attr_rule["attr"]] != attr_rule["value"]:
                             attr_match = False
                             break
                     if not attr_match:
@@ -224,9 +208,8 @@ class TEIParser(SphinxParser):
                 return rule
         return None
 
-    def _parse_single_field(
-        self: "TEIParser", parent: etree.Element, field: dict, root: etree.Element
-    ) -> None:
+    def _parse_single_field(self: "TEIParser", parent: etree.Element, field: dict, root: etree.Element) -> None:
+        """Parse a single metadata field."""
         content = root.xpath(field["content"], namespaces=namespaces)
         if len(content) > 0:
             content = content[0]
@@ -239,9 +222,8 @@ class TEIParser(SphinxParser):
             li.append(dd)
             parent.append(li)
 
-    def _parse_list_field(
-        self: "TEIParser", parent: etree.Element, field: dict, root: etree.Element
-    ) -> None:
+    def _parse_list_field(self: "TEIParser", parent: etree.Element, field: dict, root: etree.Element) -> None:
+        """Parse a list of metadata fields."""
         content = root.xpath(field["content"], namespaces=namespaces)
         if len(content) > 0:
             li = nodes.definition_list_item()

uedition/ext/tei/tei_download.js

@@ -0,0 +1,34 @@
+(function () {
+    function setup() {
+        try {
+            const dropdownMenu = document.querySelector(".article-header-buttons .dropdown-download-buttons .dropdown-menu");
+            if (dropdownMenu) {
+                const item = document.createElement("li");
+                const link = document.createElement("a");
+                link.classList.add("btn");
+                link.classList.add("btn-sm");
+                link.classList.add("dropdown-item");
+                if (location.href.endsWith("/")) {
+                    link.setAttribute("href", location.href + "index.tei");
+                } else {
+                    link.setAttribute("href", location.href.substring(0, location.href.lastIndexOf(".")) + ".tei");
+                }
+                const icon = document.createElement("span");
+                icon.classList.add("btn__icon-container");
+                icon.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512" class="svg-inline--fa fa-code" aria-hidden="true" focusable="false" data-prefix="fas" data-icon="code" data-fa-i2svg=""><!--!Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M64 0C28.7 0 0 28.7 0 64V448c0 35.3 28.7 64 64 64H320c35.3 0 64-28.7 64-64V160H256c-17.7 0-32-14.3-32-32V0H64zM256 0V128H384L256 0zM153 289l-31 31 31 31c9.4 9.4 9.4 24.6 0 33.9s-24.6 9.4-33.9 0L71 337c-9.4-9.4-9.4-24.6 0-33.9l48-48c9.4-9.4 24.6-9.4 33.9 0s9.4 24.6 0 33.9zM265 255l48 48c9.4 9.4 9.4 24.6 0 33.9l-48 48c-9.4 9.4-24.6 9.4-33.9 0s-9.4-24.6 0-33.9l31-31-31-31c-9.4-9.4-9.4-24.6 0-33.9s24.6-9.4 33.9 0z"/></svg>';
+                const text = document.createElement("text");
+                text.classList.add("btn__text-container");
+                text.innerHTML = ".tei";
+
+                link.appendChild(icon);
+                link.appendChild(text);
+                item.appendChild(link);
+                dropdownMenu.appendChild(item);
+            }
+        } catch (e) {
+            console.error(e);
+        }
+    }
+
+    window.addEventListener('DOMContentLoaded', setup);
+})();