sphinx-doc / sphinx-doc/sphinx

Using `add_node` and `dirhtml` causes nodes from `sphinx.ext` to become unknown

Open
#14,587 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

I make an extension that adds a node via add_nodes and use the dirhtml builder. At the same time I include the graphviz extension. This causes the node graphviz to become unknown and Sphinx raises an NotImplementedError:

Traceback
=========

      File "/home/kondziu/.local/share/pipx/venvs/sphinx/lib/python3.12/site-packages/docutils/nodes.py", line 2769, in unknown_departure
        raise NotImplementedError(
    NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: graphviz
How to Reproduce

conf.py:

import sys, os

sys.path.append(os.path.abspath("."))

extensions = [
    "sphinx.ext.graphviz",
    "extension"
]

extension.py:

import sphinx
import docutils

def ignore(translator, node):
    pass

class TestNode(docutils.nodes.General, docutils.nodes.Element):
    pass

def setup(app: sphinx.application.Sphinx):
    app.add_node(
            node=TestNode, override=False, dirhtml=(ignore, ignore), html=(ignore, ignore)
    )

index.rst:

Test
----

.. graphviz::

  digraph foo {
    rankdir="LR";
    a, b [shape=diamond];
    t1 [label=< <I>true</I> >; shape=box; color=green];
    f1, f2 [label=< <I>false</I> >; shape=box; color=red];
    a -> b [label=1; color=green];
    a -> f1 [label=0; color=red];
    b -> t1 [label=1; color=green];
    b -> f2 [label=0; color=red];
  }

Build with:

sphinx-build -b html . _build/            # works fine
sphinx-build -b dirhtml . _build/       # fails

Zip: example.zip

Environment Information
Sphinx 9.1.0
Sphinx extensions
extensions = [
    "sphinx.ext.graphviz",
    "extension"  # custom extension, see description
]
Additional context

Workaround:

    # The graphviz node is not defined for `dirhtml`.
    app.add_node(
        node=sphinx.ext.graphviz.graphviz,
        override=True,
        html=(sphinx.ext.graphviz.html_visit_graphviz, None),
        dirhtml=(sphinx.ext.graphviz.html_visit_graphviz, None),
        latex=(sphinx.ext.graphviz.latex_visit_graphviz, None),
        texinfo=(sphinx.ext.graphviz.texinfo_visit_graphviz, None),
        text=(sphinx.ext.graphviz.text_visit_graphviz, None),
        man=(sphinx.ext.graphviz.man_visit_graphviz, None),
    )

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the minimal conf.py, extension.py, and index.rst reproducer, then run the html and dirhtml sphinx-build commands. Inspect how sphinx.ext.graphviz registers its node for each builder alongside the custom add_node call. Done means the dirhtml build no longer treats graphviz as an unknown node while the html build continues to work.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.