sphinx-doc / sphinx-doc/sphinx

incorrect 'node already registered' error when two nodes have the same name (but are from different modules)

Open
#11,219 6 comments 0 reactions 0 assignees View on GitHub

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 have a sphinx extension that defines two different custom directives and registers corresponding custom docutils Nodes. Each custom node is called Node, but is namespaced by it's respective module, like so-

  • module_a.Node
  • module_b.Node

when running a build, i get an error-

WARNING: while setting up extension ${EXTENSION}: node class 'Node' is already registered, its visitors will be overridden

looking at the code in sphinx.util.docutils.is_node_registered I can see that nodes are registered by their class name only (cls.__name__), and not by their qualified names (cls.__qualname__). Hence you get erroneous collisions if two classes in different modules have the same name.

How to Reproduce

(you'll need Poetry installed)

git clone https://github.com/danieleades/sphinx-graph
cd sphinx-graph
git checkout table
cd docs
poetry run make html
# observe the error

i've also created a minimal reproduction here - https://github.com/danieleades/sphinx-bug-11220

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 sphinx.util.docutils.is_node_registered and trace how custom nodes are registered during extension setup. Use the linked minimal reproduction or the sphinx-graph reproduction to verify the behavior for module_a.Node and module_b.Node, then add or update tests so distinct module classes no longer produce a duplicate-registration warning.

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
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.