(this definitely looks like sphinx or docutils bug, but I'd like to let you know + ask whether you have some clue)
In short
Enabling simultaneously sphinxcontrib.images
and spinx.ext.todo
or sphinx.ext.graphviz
or various other plugins causes make epub
to crash with dirty NotImplementedError while processing .. todo
or similar directive.
Other targets (make html
, make pdf
) work fine.
Looks like this is caused by sole fact that sphinxcontrib.images
defines explicit epub callback. This somehow changes the processing chain.
I repeated it both on python2+sphinx1.8.5 and python3+sphinx3.5.4.
Longer story
I have sphinx document which uses sphinxext.todo
and contains some .. todo:
directives (and also have my custom extension of similar kind, which also shows the issue). I recently added sphinxcontrib.images
there. And, out of the sudden:
make html
and make pdf
work fine
make epub
crashes during output writing with
…
File "/home/marcink/.local/lib/python3.8/site-packages/sphinx/writers/html5.py", line 795, in unknown_visit
raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: todo_node
I found out that disabling sphinxcontrib.images
(commenting it out from extensions in conf.py
) resolves the issue, then tried deeper.
sphinxcontrib.images
has explicit epub callback:
Both sphinxext.todo
and my custom extension do not have one..
For example sphinx/ext/todo.py
has the following snippet in setup.py
:
app.add_node(todo_node,
html=(visit_todo_node, depart_todo_node),
latex=(latex_visit_todo_node, latex_depart_todo_node),
text=(visit_todo_node, depart_todo_node),
man=(visit_todo_node, depart_todo_node),
texinfo=(visit_todo_node, depart_todo_node))
Editing this code (and editing my custom extension in the same way) resolves the issue. Once I I dirty-patched sphinx/ext/todo
to:
app.add_node(todo_node,
html=(visit_todo_node, depart_todo_node),
epub=(visit_todo_node, depart_todo_node),
latex=(latex_visit_todo_node, latex_depart_todo_node),
text=(visit_todo_node, depart_todo_node),
man=(visit_todo_node, depart_todo_node),
texinfo=(visit_todo_node, depart_todo_node))
(added epub=
line) whole issue disappeared, make epub
started to work properly again.
So looks like „by default” sphinx nicely falls back to html callbacks while generating epub, but the fact that anybody in the ecosystem (here: sphinxcontrib.images
) defined explicit epub handler changes something, and makes sphinx to work differently. And out of the sudden all directives which relied on fallback to html – cause crash.