@hutusi/amytis 1.15.0 → 1.16.0

package/scripts/generate-code-group-icons.ts

@@ -0,0 +1,79 @@
+/**
+ * One-shot generator: builds CSS rules for the code-group tab icons by reading
+ * Iconify's logos / vscode-icons packs and embedding each icon as a data URI.
+ *
+ * Usage:
+ *   bun scripts/generate-code-group-icons.ts > /tmp/icons.css
+ * Then replace the block between the BEGIN/END markers in src/app/globals.css.
+ *
+ * Each icon key here corresponds to a value returned by resolveCodeGroupIcon
+ * in src/lib/code-group-icons.ts. Add to both files to support a new key.
+ */
+import { icons as logos } from '@iconify-json/logos';
+import { icons as vscodeIcons } from '@iconify-json/vscode-icons';
+
+type IconSrc = typeof logos | typeof vscodeIcons;
+
+const MAP: Record<string, { src: IconSrc; name: string }> = {
+  npm: { src: logos, name: 'npm-icon' },
+  yarn: { src: logos, name: 'yarn' },
+  pnpm: { src: logos, name: 'pnpm' },
+  bun: { src: logos, name: 'bun' },
+  deno: { src: logos, name: 'deno' },
+  typescript: { src: logos, name: 'typescript-icon' },
+  javascript: { src: logos, name: 'javascript' },
+  python: { src: logos, name: 'python' },
+  rust: { src: logos, name: 'rust' },
+  go: { src: logos, name: 'go' },
+  java: { src: logos, name: 'java' },
+  ruby: { src: logos, name: 'ruby' },
+  php: { src: logos, name: 'php' },
+  c: { src: logos, name: 'c' },
+  cpp: { src: logos, name: 'c-plusplus' },
+  html: { src: logos, name: 'html-5' },
+  css: { src: logos, name: 'css-3' },
+  json: { src: vscodeIcons, name: 'file-type-json' },
+  yaml: { src: vscodeIcons, name: 'file-type-yaml' },
+  markdown: { src: vscodeIcons, name: 'file-type-markdown' },
+  bash: { src: logos, name: 'bash-icon' },
+  docker: { src: logos, name: 'docker-icon' },
+  vite: { src: logos, name: 'vitejs' },
+  react: { src: logos, name: 'react' },
+  vue: { src: logos, name: 'vue' },
+  nextjs: { src: logos, name: 'nextjs-icon' },
+  node: { src: logos, name: 'nodejs-icon' },
+  tailwind: { src: logos, name: 'tailwindcss-icon' },
+};
+
+function buildSvg(src: IconSrc, name: string): string | null {
+  const icon = src.icons[name];
+  if (!icon) return null;
+  const w = icon.width ?? src.width ?? 24;
+  const h = icon.height ?? src.height ?? 24;
+  // Iconify "body" is the inner content of the <svg> tag; wrap to get a full SVG.
+  return `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 ${w} ${h}'>${icon.body}</svg>`;
+}
+
+function encodeDataUri(svg: string): string {
+  // CSS data URIs only require `#` and `"` to be encoded; iconify bodies use
+  // double-quoted attributes, so swap to single quotes (valid SVG).
+  return svg.replace(/"/g, "'").replace(/#/g, '%23').replace(/\n/g, '').replace(/\s+/g, ' ');
+}
+
+const lines: string[] = [
+  '/* === BEGIN: generated by scripts/generate-code-group-icons.ts — do not hand-edit === */',
+];
+for (const [key, { src, name }] of Object.entries(MAP)) {
+  const svg = buildSvg(src, name);
+  if (!svg) {
+    console.error(`Missing icon: ${name}`);
+    continue;
+  }
+  const dataUri = encodeDataUri(svg);
+  lines.push(`.cg-tab[data-cg-icon="${key}"]::before {`);
+  lines.push(`  content: '';`);
+  lines.push(`  background-image: url("data:image/svg+xml,${dataUri}");`);
+  lines.push(`}`);
+}
+lines.push('/* === END: generated icons === */');
+console.log(lines.join('\n'));

package/scripts/render-rst.py

@@ -563,6 +563,140 @@ def strip_preamble_nodes(document: Any) -> Any:
     return stripped
 
 
+def _language_from_classes(classes: list[str] | None) -> str:
+    """Recover the source language from a literal_block's class list when the
+    explicit `language` attribute is absent. Docutils stores ``.. code-block:: foo``
+    as classes=['code', 'foo']; the first class that isn't a docutils-internal
+    marker is the language name.
+    """
+    if not classes:
+        return ""
+    for cls in classes:
+        if cls not in ("code", "literal-block", "linenos"):
+            return cls
+    return ""
+
+
+def _build_amytis_code_marker(
+    text: str,
+    language: str,
+    highlight_lines: list[int] | None,
+    linenos: bool,
+    title: str | None,
+) -> str:
+    """Build the opaque <pre data-amytis-code> marker that the JS-side
+    Shiki post-processor in src/lib/shiki-rst.ts replaces with highlighted HTML.
+    """
+    attrs = ['data-amytis-code=""']
+    if language:
+        attrs.append(f'data-language="{html.escape(language, quote=True)}"')
+    if highlight_lines:
+        attrs.append(
+            f'data-highlight-lines="{",".join(str(n) for n in highlight_lines)}"'
+        )
+    if linenos:
+        attrs.append('data-line-numbers="true"')
+    if title:
+        attrs.append(f'data-title="{html.escape(title, quote=True)}"')
+
+    escaped = html.escape(text, quote=False)
+    return f'<pre {" ".join(attrs)}><code>{escaped}</code></pre>'
+
+
+def _build_inner_block_marker(block: Any) -> tuple[str, str]:
+    """Helper: build the per-block <pre data-amytis-code> marker AND return the
+    tab label (from the new `:label:` option, or the language as fallback).
+    Used by both the standalone-literal_block path and the code-group path.
+    """
+    classes = list(block.get("classes") or [])
+    language = block.get("language") or _language_from_classes(classes)
+    highlight_args = block.get("highlight_args") or {}
+    hl_lines = list(highlight_args.get("hl_lines") or [])
+    linenos = "linenos" in classes
+    caption_text = block.get("amytis_caption")  # set by the directive when :caption: is present
+    label = block.get("amytis_label") or language or ""
+
+    marker = _build_amytis_code_marker(
+        text=block.astext(),
+        language=language,
+        highlight_lines=hl_lines,
+        linenos=linenos,
+        title=caption_text,
+    )
+    return marker, label
+
+
+def transform_literal_blocks_to_markers(document: Any) -> None:
+    """Replace every literal_block with an opaque <pre data-amytis-code> marker
+    so the JS-side post-processor can run Shiki uniformly. Caption-bearing
+    literal-block-wrapper containers are flattened into the marker's data-title.
+
+    Code-group containers (emitted by the .. code-group:: directive) are
+    handled FIRST so their child literal_blocks are consumed before the
+    standalone-block pass sees them — otherwise the standalone pass would
+    replace them and we'd lose the grouping wrapper.
+    """
+    from docutils import nodes
+    import json
+
+    # Pass 1: collapse caption containers so child literal_blocks carry their caption
+    # as a custom attribute. (Doing this once here means the helper doesn't need to
+    # walk back up to find a parent literal-block-wrapper.)
+    for container in list(document.findall(nodes.container)):
+        if "literal-block-wrapper" not in (container.get("classes") or []):
+            continue
+        caption_node = next(
+            (c for c in container.children if isinstance(c, nodes.caption)),
+            None,
+        )
+        inner_block = next(
+            (c for c in container.children if isinstance(c, nodes.literal_block)),
+            None,
+        )
+        if caption_node is not None and inner_block is not None:
+            inner_block["amytis_caption"] = caption_node.astext().strip()
+            container.parent.replace(container, inner_block)
+
+    # Pass 2: handle code-group containers. The directive marks them with the
+    # 'amytis-code-group-source' class. Per CLAUDE.md "strict build over silent
+    # runtime failure", malformed groups raise rather than getting dropped, and
+    # group ids are issued from a monotonic counter so two groups with identical
+    # label sets never share an id (which would couple their tab radios).
+    group_counter = 0
+    for container in list(document.findall(nodes.container)):
+        if "amytis-code-group-source" not in (container.get("classes") or []):
+            continue
+
+        inner_blocks = list(container.findall(nodes.literal_block))
+        if not inner_blocks:
+            raise RstRenderError(
+                "Empty or malformed '.. code-group::' directive: expected at least one nested .. code-block:: child."
+            )
+
+        markers: list[str] = []
+        labels: list[str] = []
+        for block in inner_blocks:
+            marker, label = _build_inner_block_marker(block)
+            markers.append(marker)
+            labels.append(label)
+
+        group_counter += 1
+        group_id = f"rst-{group_counter}"
+        labels_json = html.escape(json.dumps(labels, ensure_ascii=False), quote=True)
+        wrapper_html = (
+            f'<div data-amytis-code-group="" data-labels="{labels_json}" '
+            f'data-group-id="{group_id}">'
+            + "".join(markers)
+            + "</div>"
+        )
+        container.parent.replace(container, nodes.raw("", wrapper_html, format="html"))
+
+    # Pass 3: replace remaining (non-grouped) literal_blocks.
+    for block in list(document.findall(nodes.literal_block)):
+        marker, _ = _build_inner_block_marker(block)
+        block.parent.replace(block, nodes.raw("", marker, format="html"))
+
+
 def extract_html_body_from_doctree(document: Any) -> str:
     from docutils.core import publish_from_doctree
 
@@ -598,22 +732,92 @@ def build_output(document: Any, source_file: Path, image_base_slug: str, warning
         raise RstRenderError("Missing document title.")
 
     assets = extract_assets(document, source_file, image_base_slug)
+    # Read-only extractions first; the literal-block transformation mutates the tree.
+    text = extract_body_text(document)
+    headings = extract_headings(document)
+    metadata = extract_metadata(document)
+
+    transform_literal_blocks_to_markers(document)
     html_body = extract_html_body_from_doctree(strip_preamble_nodes(document))
 
     return {
         "title": title_node.astext().strip(),
         "html": rewrite_html_assets(html_body, assets),
-        "text": extract_body_text(document),
-        "headings": extract_headings(document),
-        "metadata": extract_metadata(document),
+        "text": text,
+        "headings": headings,
+        "metadata": metadata,
         "assets": assets,
         "warnings": list(dict.fromkeys(warnings)),
     }
 
 
+_amytis_directives_registered = False
+
+
+def register_amytis_directives() -> None:
+    """Register the .. code-group:: directive and a code-block subclass that
+    accepts a :label: option. Both are global to the docutils registry, so
+    registering once per process is enough.
+
+    The code-block override only ADDS the :label: option; standard behavior
+    (language argument, :linenos:, :emphasize-lines:, :caption:) goes through
+    docutils' built-in implementation unchanged. The label is stashed on the
+    resulting literal_block via a custom amytis_label attribute and consumed
+    by transform_literal_blocks_to_markers.
+    """
+    global _amytis_directives_registered
+    if _amytis_directives_registered:
+        return
+
+    from docutils import nodes
+    from docutils.parsers.rst import Directive, directives
+    from docutils.parsers.rst.directives.body import CodeBlock as BaseCodeBlock
+
+    class LabeledCodeBlock(BaseCodeBlock):
+        option_spec = {
+            **BaseCodeBlock.option_spec,
+            "label": directives.unchanged,
+        }
+
+        def run(self):
+            result = super().run()
+            label = self.options.get("label")
+            if label:
+                for node in result:
+                    for lb in node.findall(nodes.literal_block):
+                        lb["amytis_label"] = label
+            return result
+
+    class CodeGroup(Directive):
+        """Wrap nested code-blocks into a tabbed code-group.
+
+        Body content is parsed as rST and contributes literal_block children;
+        transform_literal_blocks_to_markers later consumes the whole subtree
+        and emits the <div data-amytis-code-group> wrapper marker.
+        """
+
+        has_content = True
+        required_arguments = 0
+        optional_arguments = 0
+        option_spec = {}
+
+        def run(self):
+            wrapper = nodes.container()
+            wrapper["classes"].append("amytis-code-group-source")
+            self.state.nested_parse(self.content, self.content_offset, wrapper)
+            return [wrapper]
+
+    directives.register_directive("code-block", LabeledCodeBlock)
+    directives.register_directive("code", LabeledCodeBlock)
+    directives.register_directive("sourcecode", LabeledCodeBlock)
+    directives.register_directive("code-group", CodeGroup)
+    _amytis_directives_registered = True
+
+
 def render_single_file(source_file: Path, image_base_slug: str, strict: bool) -> dict[str, Any]:
     from docutils.core import publish_doctree
 
+    register_amytis_directives()
     warnings: list[str] = []
     source = normalize_legacy_doc_role_syntax(source_file.read_text(encoding="utf-8"))
     with temporary_role_overrides(source_file, warnings):