typsphinx 0.4.4__tar.gz → 0.6.0__tar.gz

{typsphinx-0.4.4/typsphinx.egg-info → typsphinx-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typsphinx
-Version: 0.4.4
+Version: 0.6.0
 Summary: Sphinx extension for Typst output
 Author-email: YuSabo <yusabo90002@gmail.com>
 License-Expression: MIT
@@ -13,18 +13,16 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Sphinx :: Extension
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Documentation
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: sphinx<9,>=5.0
-Requires-Dist: docutils<0.22,>=0.18
-Requires-Dist: typst<0.15,>=0.14.1
+Requires-Dist: sphinx<10,>=9.1
+Requires-Dist: docutils<0.23,>=0.21
+Requires-Dist: typst<0.16,>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pytest<10,>=8.4; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -34,14 +32,14 @@ Requires-Dist: black<27,>=26; extra == "dev"
 Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
 Requires-Dist: mypy<3.0,>=1.13; extra == "dev"
 Requires-Dist: pre-commit>=3.0; extra == "dev"
-Requires-Dist: types-docutils>=0.18; extra == "dev"
+Requires-Dist: types-docutils>=0.21; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pypdf<7,>=6.14; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: furo>=2024.0; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints>=1.0; extra == "docs"
 Requires-Dist: sphinx-intl>=2.0; extra == "docs"
-Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "docs"
 Dynamic: license-file
 
 # typsphinx
@@ -66,7 +64,7 @@ typsphinx is a Sphinx extension that enables generating Typst documents from reS
 - **Convert Sphinx documentation to Typst format**: Seamlessly transform your reStructuredText/Markdown documents
 - **Standard docutils nodes**: Full support for paragraphs, sections, lists, tables, admonitions, and more
 - **Mathematical expressions**:
-  - LaTeX syntax via mitex (`@preview/mitex:0.2.4`)
+  - LaTeX syntax via mitex (`@preview/mitex:0.2.7`)
   - Native Typst math syntax
 - **Code blocks with syntax highlighting**: Using codly package (`@preview/codly:1.3.0`)
   - Automatic line numbering
@@ -80,9 +78,9 @@ typsphinx is a Sphinx extension that enables generating Typst documents from reS
 
 ## Requirements
 
-- Python 3.10 or higher
-- Sphinx 5.0 or higher
-- typst-py 0.11.1 or higher
+- Python 3.12 or higher
+- Sphinx 9.1 or higher
+- typst-py 0.15.0 or higher
 
 ## Installation
 
@@ -266,7 +264,7 @@ This project uses uv for fast package management and follows TDD (Test-Driven De
 # Install with development dependencies
 uv sync --extra dev
 
-# Run tests (375 tests, 91% coverage)
+# Run tests (413 tests)
 uv run pytest
 
 # Run tests with coverage report
@@ -278,7 +276,7 @@ uv run tox
 # Run specific tox environments
 uv run tox -e lint          # Run linters (black, ruff)
 uv run tox -e type          # Run type checking (mypy)
-uv run tox -e py311         # Run tests on Python 3.11
+uv run tox -e py312         # Run tests on Python 3.12
 uv run tox -e docs-html     # Build HTML documentation
 uv run tox -e docs-pdf      # Build PDF documentation
 uv run tox -e docs          # Build both HTML and PDF docs
@@ -286,7 +284,7 @@ uv run tox -e docs          # Build both HTML and PDF docs
 
 ### Testing Strategy
 
-- **Unit tests**: 375 tests covering all major components
+- **Unit tests**: 413 tests covering all major components
 - **Integration tests**: Full build process validation
 - **Example projects**: `examples/basic/` and `examples/advanced/`
 - **Code coverage**: 93% overall
@@ -366,5 +364,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.4.2) - Production ready
-**Python**: 3.10+ | **Sphinx**: 5.0+ | **Typst**: 0.11.1+
+**Status**: Stable (v0.5.0) - Production ready
+**Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.4.4 → typsphinx-0.6.0}/README.md

@@ -20,7 +20,7 @@ typsphinx is a Sphinx extension that enables generating Typst documents from reS
 - **Convert Sphinx documentation to Typst format**: Seamlessly transform your reStructuredText/Markdown documents
 - **Standard docutils nodes**: Full support for paragraphs, sections, lists, tables, admonitions, and more
 - **Mathematical expressions**:
-  - LaTeX syntax via mitex (`@preview/mitex:0.2.4`)
+  - LaTeX syntax via mitex (`@preview/mitex:0.2.7`)
   - Native Typst math syntax
 - **Code blocks with syntax highlighting**: Using codly package (`@preview/codly:1.3.0`)
   - Automatic line numbering
@@ -34,9 +34,9 @@ typsphinx is a Sphinx extension that enables generating Typst documents from reS
 
 ## Requirements
 
-- Python 3.10 or higher
-- Sphinx 5.0 or higher
-- typst-py 0.11.1 or higher
+- Python 3.12 or higher
+- Sphinx 9.1 or higher
+- typst-py 0.15.0 or higher
 
 ## Installation
 
@@ -220,7 +220,7 @@ This project uses uv for fast package management and follows TDD (Test-Driven De
 # Install with development dependencies
 uv sync --extra dev
 
-# Run tests (375 tests, 91% coverage)
+# Run tests (413 tests)
 uv run pytest
 
 # Run tests with coverage report
@@ -232,7 +232,7 @@ uv run tox
 # Run specific tox environments
 uv run tox -e lint          # Run linters (black, ruff)
 uv run tox -e type          # Run type checking (mypy)
-uv run tox -e py311         # Run tests on Python 3.11
+uv run tox -e py312         # Run tests on Python 3.12
 uv run tox -e docs-html     # Build HTML documentation
 uv run tox -e docs-pdf      # Build PDF documentation
 uv run tox -e docs          # Build both HTML and PDF docs
@@ -240,7 +240,7 @@ uv run tox -e docs          # Build both HTML and PDF docs
 
 ### Testing Strategy
 
-- **Unit tests**: 375 tests covering all major components
+- **Unit tests**: 413 tests covering all major components
 - **Integration tests**: Full build process validation
 - **Example projects**: `examples/basic/` and `examples/advanced/`
 - **Code coverage**: 93% overall
@@ -320,5 +320,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.4.2) - Production ready
-**Python**: 3.10+ | **Sphinx**: 5.0+ | **Typst**: 0.11.1+
+**Status**: Stable (v0.5.0) - Production ready
+**Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.4.4 → typsphinx-0.6.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typsphinx"
-version = "0.4.4"
+version = "0.6.0"
 description = "Sphinx extension for Typst output"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = "MIT"
 authors = [
     {name = "YuSabo", email = "yusabo90002@gmail.com"}
@@ -18,8 +18,6 @@ classifiers = [
     "Framework :: Sphinx :: Extension",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Documentation :: Sphinx",
@@ -27,9 +25,9 @@ classifiers = [
 ]
 
 dependencies = [
-    "sphinx>=5.0,<9",
-    "docutils>=0.18,<0.22",
-    "typst>=0.14.1,<0.15",
+    "sphinx>=9.1,<10",
+    "docutils>=0.21,<0.23",
+    "typst>=0.15.0,<0.16",
 ]
 
 [project.optional-dependencies]
@@ -42,15 +40,15 @@ dev = [
     "ruff>=0.15,<0.16",
     "mypy>=1.13,<3.0",
     "pre-commit>=3.0",
-    "types-docutils>=0.18",
+    "types-docutils>=0.21",
     "twine>=5.0",
     "build>=1.0",
+    "pypdf>=6.14,<7",
 ]
 docs = [
     "furo>=2024.0",
     "sphinx-autodoc-typehints>=1.0",
     "sphinx-intl>=2.0",
-    "tomli>=2.0; python_version < '3.11'",
 ]
 
 [project.urls]
@@ -82,10 +80,23 @@ markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
     "integration: marks tests as integration tests",
 ]
+filterwarnings = [
+    "error::DeprecationWarning",
+    # Escalated beyond CONTEXT.md's literal "DeprecationWarning" text: Sphinx's own
+    # RemovedInSphinxNNWarning family (e.g. builder.app) subclasses
+    # PendingDeprecationWarning, not DeprecationWarning — without this line, future
+    # Sphinx deprecations would pass through un-gated. See 08-RESEARCH.md Pitfall 2.
+    "error::PendingDeprecationWarning",
+    # No third-party ignore:: entries needed as of Sphinx 9.1.0/docutils 0.22.4/
+    # typst-py 0.15.0 (verified zero third-party warnings in 08-RESEARCH.md). If a
+    # future dependency bump introduces one, add a targeted
+    # ignore::DeprecationWarning:<module> entry here — do not weaken the two `error`
+    # lines above.
+]
 
 [tool.black]
 line-length = 88
-target-version = ["py310", "py311", "py312", "py313"]
+target-version = ["py312", "py313"]
 include = '\.pyi?$'
 exclude = '''
 /(
@@ -100,7 +111,7 @@ exclude = '''
 
 [tool.ruff]
 line-length = 88
-target-version = "py310"
+target-version = "py312"
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "T20"]
@@ -117,7 +128,7 @@ ignore = [
 ]
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.12"
 warn_return_any = false
 warn_unused_configs = true
 disallow_untyped_defs = false

typsphinx-0.6.0/tests/test_admonitions.py

@@ -0,0 +1,433 @@
+"""
+Tests for admonition node conversion to Typst gentle-clues.
+
+Task 3.4: アドモニション（Admonition）の変換
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import states
+from docutils.utils import Reporter
+from sphinx import addnodes
+from sphinx.testing.util import SphinxTestApp
+
+from typsphinx.translator import TypstTranslator
+from typsphinx.writer import TypstWriter
+
+
+def create_document():
+    """Helper function to create a minimal document with reporter."""
+    reporter = Reporter("", 2, 4)
+    doc = nodes.document("", reporter=reporter)
+    doc.settings = states.Struct()
+    doc.settings.env = None
+    doc.settings.language_code = "en"
+    doc.settings.strict_visitor = False
+    return doc
+
+
+class TestAdmonitionConversion:
+    """Test admonition node conversion using gentle-clues package."""
+
+    def test_note_converts_to_info(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.note converts to info[]."""
+        # Create a note admonition
+        note = nodes.note()
+        para = nodes.paragraph(text="This is a note.")
+        note += para
+
+        # Create document
+        doc = create_document()
+        doc += note
+
+        # Translate
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert 'par({text("This is a note.")})' in output
+
+    def test_warning_converts_to_warning(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.warning converts to warning[]."""
+        warning = nodes.warning()
+        para = nodes.paragraph(text="This is a warning.")
+        warning += para
+
+        doc = create_document()
+        doc += warning
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "warning({" in output
+        assert "warning[" not in output
+        assert 'par({text("This is a warning.")})' in output
+
+    def test_tip_converts_to_tip(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.tip converts to tip[]."""
+        tip = nodes.tip()
+        para = nodes.paragraph(text="Here's a tip.")
+        tip += para
+
+        doc = create_document()
+        doc += tip
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "tip({" in output
+        assert "tip[" not in output
+        assert 'par({text("Here\'s a tip.")})' in output
+
+    def test_important_converts_to_warning_with_title(
+        self, temp_sphinx_app: SphinxTestApp
+    ):
+        """Test that nodes.important converts to warning(title: "Important")[]."""
+        important = nodes.important()
+        para = nodes.paragraph(text="This is important.")
+        important += para
+
+        doc = create_document()
+        doc += important
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "warning({" in output
+        assert "warning[" not in output
+        assert ', title: "Important"' in output
+        assert 'par({text("This is important.")})' in output
+
+    def test_caution_converts_to_warning(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.caution converts to warning[]."""
+        caution = nodes.caution()
+        para = nodes.paragraph(text="Be cautious.")
+        caution += para
+
+        doc = create_document()
+        doc += caution
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "warning({" in output
+        assert "warning[" not in output
+        assert 'par({text("Be cautious.")})' in output
+
+    def test_seealso_converts_to_info_with_title(self, temp_sphinx_app: SphinxTestApp):
+        """Test that addnodes.seealso converts to info(title: "See Also")[]."""
+        seealso = addnodes.seealso()
+        para = nodes.paragraph(text="See related documentation.")
+        seealso += para
+
+        doc = create_document()
+        doc += seealso
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert ', title: "See Also"' in output
+        assert 'par({text("See related documentation.")})' in output
+
+    def test_admonition_with_multiple_paragraphs(self, temp_sphinx_app: SphinxTestApp):
+        """Test admonition with multiple paragraphs."""
+        note = nodes.note()
+        para1 = nodes.paragraph(text="First paragraph.")
+        para2 = nodes.paragraph(text="Second paragraph.")
+        note += para1
+        note += para2
+
+        doc = create_document()
+        doc += note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert 'par({text("First paragraph.")})' in output
+        assert 'par({text("Second paragraph.")})' in output
+
+    def test_nested_admonitions(self, temp_sphinx_app: SphinxTestApp):
+        """Test nested admonitions."""
+        outer_note = nodes.note()
+        para1 = nodes.paragraph(text="Outer note.")
+        inner_warning = nodes.warning()
+        para2 = nodes.paragraph(text="Inner warning.")
+        inner_warning += para2
+        outer_note += para1
+        outer_note += inner_warning
+
+        doc = create_document()
+        doc += outer_note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert 'par({text("Outer note.")})' in output
+        assert "warning({" in output
+        assert "warning[" not in output
+        assert 'par({text("Inner warning.")})' in output
+
+    def test_nested_list_in_note(self, temp_sphinx_app: SphinxTestApp):
+        """Test a bullet list nested inside a note (D-05)."""
+        note = nodes.note()
+        bullet_list = nodes.bullet_list()
+        item1 = nodes.list_item()
+        item1 += nodes.paragraph(text="Item one.")
+        item2 = nodes.list_item()
+        item2 += nodes.paragraph(text="Item two.")
+        bullet_list += item1
+        bullet_list += item2
+        note += bullet_list
+
+        doc = create_document()
+        doc += note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        # The note stays in code-mode content-block form and the nested
+        # list's code-mode form evaluates inside it (no literal-source leak).
+        assert "info({" in output
+        assert "info[" not in output
+        assert "list(" in output
+        assert 'text("Item one.")' in output
+        assert 'text("Item two.")' in output
+
+    def test_nested_code_block_in_note(self, temp_sphinx_app: SphinxTestApp):
+        """Test a literal/code block nested inside a note (D-05)."""
+        note = nodes.note()
+        literal_block = nodes.literal_block(text="x = 1")
+        note += literal_block
+
+        doc = create_document()
+        doc += note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert "```" in output
+        assert "x = 1" in output
+
+    def test_admonition_with_title_in_content(self, temp_sphinx_app: SphinxTestApp):
+        """Test admonition with custom title in first paragraph."""
+        # In Sphinx, custom admonitions have the title as the first child
+        note = nodes.note()
+        title = nodes.title(text="Custom Title")
+        para = nodes.paragraph(text="Content here.")
+        note += title
+        note += para
+
+        doc = create_document()
+        doc += note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        # Should use the dynamic (node-derived) title buffered as a code
+        # block, emitted exactly once, with the body evaluating in code mode.
+        assert "info({" in output
+        assert "info[" not in output
+        assert ", title: {" in output
+        assert output.count("Custom Title") == 1
+        assert "heading(" not in output  # double-emission bug fixed
+        assert 'par({text("Content here.")})' in output
+
+    def test_admonition_title_preserves_inline_markup(
+        self, temp_sphinx_app: SphinxTestApp
+    ):
+        """Test that an admonition title preserves inline markup (D-02).
+
+        The title's rendered content is captured via the buffer-swap idiom
+        (routing through the normal inline visitors) rather than flattened
+        with node.astext(), so an emphasis child inside the title survives
+        as an emph(...) code-mode call instead of being reduced to plain
+        text. This also locks down the title double-emission regression
+        found in RESEARCH.md: heading( must never appear in the output.
+
+        Note: nodes.note() does not carry a title in real rST usage; this
+        is a constructed shape used purely to exercise the admonition-aware
+        visit_title/depart_title branch. The real docutils shape for a
+        title-bearing admonition is nodes.admonition (generic `.. admonition::`),
+        covered by Plan 03's D-06 generic-admonition test.
+        """
+        note = nodes.note()
+        title = nodes.title()
+        title += nodes.Text("Custom ")
+        title += nodes.emphasis(text="Title")
+        para = nodes.paragraph(text="Content here.")
+        note += title
+        note += para
+
+        doc = create_document()
+        doc += note
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "info({" in output
+        assert "info[" not in output
+        assert ", title: {" in output
+        assert "emph({" in output
+        assert output.count("Custom") == 1
+        assert output.count("Title") == 1
+        assert "heading(" not in output  # double-emission bug fixed
+
+    def test_hint_converts_to_tip(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.hint converts to tip[] (D-06).
+
+        gentle-clues 1.3.1 has no dedicated `hint` clue; `tip` is the
+        verified closest analog.
+        """
+        hint = nodes.hint()
+        para = nodes.paragraph(text="Here's a hint.")
+        hint += para
+
+        doc = create_document()
+        doc += hint
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "tip({" in output
+        assert "tip[" not in output
+        assert 'par({text("Here\'s a hint.")})' in output
+
+    def test_error_converts_to_error(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.error converts to error[] (D-06)."""
+        error = nodes.error()
+        para = nodes.paragraph(text="This is an error.")
+        error += para
+
+        doc = create_document()
+        doc += error
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "error({" in output
+        assert "error[" not in output
+        assert 'par({text("This is an error.")})' in output
+
+    def test_danger_converts_to_danger(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.danger converts to danger[] (D-06)."""
+        danger = nodes.danger()
+        para = nodes.paragraph(text="This is dangerous.")
+        danger += para
+
+        doc = create_document()
+        doc += danger
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "danger({" in output
+        assert "danger[" not in output
+        assert 'par({text("This is dangerous.")})' in output
+
+    def test_attention_converts_to_warning(self, temp_sphinx_app: SphinxTestApp):
+        """Test that nodes.attention converts to warning[] (D-06).
+
+        gentle-clues 1.3.1 has no dedicated `attention` clue; `warning` is
+        the verified analog, consistent with the existing `caution`/
+        `important` -> `warning` precedent.
+        """
+        attention = nodes.attention()
+        para = nodes.paragraph(text="Pay attention.")
+        attention += para
+
+        doc = create_document()
+        doc += attention
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "warning({" in output
+        assert "warning[" not in output
+        assert 'par({text("Pay attention.")})' in output
+
+    def test_generic_admonition_converts_to_clue(self, temp_sphinx_app: SphinxTestApp):
+        """Test that a generic nodes.admonition converts to clue[] (D-06).
+
+        Uses the real docutils shape produced by `.. admonition:: <title>` —
+        a `nodes.admonition` with a real `nodes.title` child — rather than
+        an injected title on an unrelated admonition type. The title flows
+        through the same buffer-swap `visit_title`/`depart_title` path used
+        by all other admonition types.
+        """
+        admonition = nodes.admonition()
+        title = nodes.title(text="My Note")
+        para = nodes.paragraph(text="Generic admonition body.")
+        admonition += title
+        admonition += para
+
+        doc = create_document()
+        doc += admonition
+
+        writer = TypstWriter(temp_sphinx_app.builder)
+        writer.document = doc
+        translator = TypstTranslator(doc, temp_sphinx_app.builder)
+        doc.walkabout(translator)
+
+        output = translator.astext()
+        assert "clue({" in output
+        assert "clue[" not in output
+        assert ", title: {" in output
+        assert output.count("My Note") == 1
+        assert "heading(" not in output
+        assert 'par({text("Generic admonition body.")})' in output