sphinx-doc / sphinx-doc/sphinx
Using `add_node` and `dirhtml` causes nodes from `sphinx.ext` to become unknown
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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