`NotionTranslator fails with: visiting unknown node type: <X> (desc, Text, index, tabular_col_spec, ...) – incompatible with Sphinx 7/8`

[raianeli31]

Hello!

I am using the latest Sphinx 8.2.x with sphinx-notionbuilder, and the Notion builder consistently fails with errors like:

NotImplementedError: <class 'sphinx_notion.NotionTranslator'> visiting unknown node type: desc
NotImplementedError: ... node type: tabular_col_spec
NotImplementedError: ... node type: index
NotImplementedError: ... node type: compact_paragraph
NotImplementedError: ... node type: Text

These nodes are core elements of modern Sphinx/Docutils:

• desc is essential for autodoc/autosummary
• Text is a basic Docutils node
• compact_paragraph, tabular_col_spec, and index are extremely common in Sphinx processing

This makes the Notion builder effectively unusable on any real project, especially one relying on autodoc/autosummary.

Minimum reproduction

Just enabling:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "myst_nb",
    "sphinx_notion",
]

and building with:

sphinx-build -b notion source build/notion

causes the failure.

Current workaround

I had to monkey-patch the translator in conf.py:

from sphinx_notion import NotionTranslator

def ignore_unknown_visit(self, node): pass
def ignore_unknown_departure(self, node): pass

NotionTranslator.unknown_visit = ignore_unknown_visit
NotionTranslator.unknown_departure = ignore_unknown_departure

and also patch visit_Text, since the translator does not implement it and also has no add_text() method.

Request

Could you:

1. Provide fallback handlers for common nodes, or
2. Add a generic handler in unknown_visit/unknown_departure so the builder doesn’t crash, or
3. Update the NotionTranslator to match Sphinx 7/8 node types?

This would make the builder usable again with modern Sphinx.

Thanks!