Sphinx<8.1; Can't instantiate sphinx.application.Sphinx twice in the same process with warningiserror

[Alxe]

Describe the bug

When using warningiserror and calling Sphinx programatically, the second call to Sphinx.__init__ will trigger a warning that gets turned into an error.

from sphinx.application import Sphinx

# Calls `sphinx.utils.docutils.register_node` for, among others, `toctree`.
s1 = Sphinx(".", None, "out", "toctree", "html", warningiserror=True)

# Because `sphinx.utils.docutils.register_node` uses `docutils.nodes.GenericNodeVisitor` as state machine, any new invocation fails.
s2 = Sphinx(".", None, "out", "toctree", "html", warningiserror=True)

This issue doesn't reproduce in 8.1, after #12743, but the logging messages are still emitted.
The latter can be problematic if you're using warning-is-error by yourself, e.g. by installing a io.StringIO as s2.warning and checking there.

How to Reproduce

from sphinx.application import Sphinx

# Calls `sphinx.utils.docutils.register_node` for, among others, `toctree`.
s1 = Sphinx(".", None, "out", "toctree", "html", warningiserror=True)

# Because `sphinx.utils.docutils.register_node` uses `docutils.nodes.GenericNodeVisitor` as state machine, any new invocation fails.
s2 = Sphinx(".", None, "out", "toctree", "html", warningiserror=True)

Environment Information

Platform:              darwin; (macOS-15.5-arm64-arm-64bit-Mach-O)
Python version:        3.13.2 (main, Feb  4 2025, 14:51:09) [Clang 16.0.0 (clang-1600.0.26.6)])
Python implementation: CPython
Sphinx version:        7.4.7
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.1

Sphinx extensions

Additional context

I am wrapping Sphinx into an internal application that bundles rST generation and using custom Sphinx Directives.

[Alxe]

Not to overload the original report, you can see the entire interaction in IPython below:

In [1]: import sphinx.application as sphinx_application

In [2]: s = sphinx_application.Sphinx(".", None, "out", ".", "html", warningiserror=True)
Running Sphinx v7.4.7
loading translations [en]... done

In [3]: s = sphinx_application.Sphinx(".", None, "out", ".", "html", warningiserror=True)
Running Sphinx v7.4.7
loading translations [en]... done
---------------------------------------------------------------------------
SphinxWarning                             Traceback (most recent call last)
Cell In[3], line 1
----> 1 s = sphinx_application.Sphinx(".", None, "out", ".", "html", warningiserror=True)

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/application.py:249, in Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning, freshenv, warningiserror, tags, verbosity, parallel, keep_going, pdb)
    246 # load all built-in extension modules, first-party extension modules,
    247 # and first-party themes
    248 for extension in builtin_extensions:
--> 249     self.setup_extension(extension)
    251 # load all user-given extension modules
    252 for extension in self.config.extensions:

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/application.py:429, in Sphinx.setup_extension(self, extname)
    422 """Import and setup a Sphinx extension module.
    423
    424 Load the extension given by the module *name*.  Use this if your
    425 extension needs the features provided by another extension.  No-op if
    426 called twice.
    427 """
    428 logger.debug('[app] setting up extension: %r', extname)
--> 429 self.registry.load_extension(self, extname)

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/registry.py:466, in SphinxComponentRegistry.load_extension(self, app, extname)
    464 else:
    465     try:
--> 466         metadata = setup(app)
    467     except VersionRequirementError as err:
    468         # add the extension name to the version required
    469         raise VersionRequirementError(
    470             __('The %s extension used by this project needs at least '
    471                'Sphinx v%s; it therefore cannot be built with this '
    472                'version.') % (extname, err),
    473         ) from err

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/addnodes.py:560, in setup(app)
    559 def setup(app: Sphinx) -> ExtensionMetadata:
--> 560     app.add_node(toctree)
    562     app.add_node(desc)
    563     app.add_node(desc_signature)

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/application.py:643, in Sphinx.add_node(self, node, override, **kwargs)
    641 logger.debug('[app] adding node: %r', (node, kwargs))
    642 if not override and docutils.is_node_registered(node):
--> 643     logger.warning(__('node class %r is already registered, '
    644                       'its visitors will be overridden'),
    645                    node.__name__, type='app', subtype='add_node')
    646 docutils.register_node(node)
    647 self.registry.add_translation_handlers(node, **kwargs)

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/util/logging.py:184, in SphinxLoggerAdapter.warning(self, msg, type, subtype, location, nonl, color, once, *args, **kwargs)
    150 def warning(  # type: ignore[override]
    151     self,
    152     msg: object,
   (...)
    160     **kwargs: Any,
    161 ) -> None:
    162     """Log a sphinx warning.
    163
    164     It is recommended to include a ``type`` and ``subtype`` for warnings as
   (...)
    182         if a previous warning already has same ``msg``, ``args`` and ``once=True``.
    183     """
--> 184     return super().warning(
    185         msg,
    186         *args,
    187         type=type,
    188         subtype=subtype,
    189         location=location,
    190         nonl=nonl,
    191         color=color,
    192         once=once,
    193         **kwargs,
    194     )

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1912, in LoggerAdapter.warning(self, msg, *args, **kwargs)
   1908 def warning(self, msg, *args, **kwargs):
   1909     """
   1910     Delegate a warning call to the underlying logger.
   1911     """
-> 1912     self.log(WARNING, msg, *args, **kwargs)

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/util/logging.py:131, in SphinxLoggerAdapter.log(self, level, msg, *args, **kwargs)
    127 def log(  # type: ignore[override]
    128     self, level: int | str, msg: str, *args: Any, **kwargs: Any,
    129 ) -> None:
    130     if isinstance(level, int):
--> 131         super().log(level, msg, *args, **kwargs)
    132     else:
    133         levelno = LEVEL_NAMES[level]

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1944, in LoggerAdapter.log(self, level, msg, *args, **kwargs)
   1942 if self.isEnabledFor(level):
   1943     msg, kwargs = self.process(msg, kwargs)
-> 1944     self.logger.log(level, msg, *args, **kwargs)

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1589, in Logger.log(self, level, msg, *args, **kwargs)
   1587         return
   1588 if self.isEnabledFor(level):
-> 1589     self._log(level, msg, args, **kwargs)

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1664, in Logger._log(self, level, msg, args, exc_info, extra, stack_info, stacklevel)
   1661         exc_info = sys.exc_info()
   1662 record = self.makeRecord(self.name, level, fn, lno, msg, args,
   1663                          exc_info, func, extra, sinfo)
-> 1664 self.handle(record)

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1680, in Logger.handle(self, record)
   1678 if isinstance(maybe_record, LogRecord):
   1679     record = maybe_record
-> 1680 self.callHandlers(record)

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1736, in Logger.callHandlers(self, record)
   1734     found = found + 1
   1735     if record.levelno >= hdlr.level:
-> 1736         hdlr.handle(record)
   1737 if not c.propagate:
   1738     c = None    #break out

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:1021, in Handler.handle(self, record)
   1010 def handle(self, record):
   1011     """
   1012     Conditionally emit the specified logging record.
   1013
   (...)
   1019     if it passed all filters, otherwise a false value is returned.
   1020     """
-> 1021     rv = self.filter(record)
   1022     if isinstance(rv, LogRecord):
   1023         record = rv

File /opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py:866, in Filterer.filter(self, record)
    864 for f in self.filters:
    865     if hasattr(f, 'filter'):
--> 866         result = f.filter(record)
    867     else:
    868         result = f(record) # assume callable - will raise if not

File /private/var/tmp/sphinx_issue/.venv/lib/python3.13/site-packages/sphinx/util/logging.py:473, in WarningIsErrorFilter.filter(self, record)
    471         raise exc from record.exc_info[1]
    472     else:
--> 473         raise exc
    474 else:
    475     return True

SphinxWarning: node class 'toctree' is already registered, its visitors will be overridden

[AA-Turner]

We only support the latest version of Sphinx.

A

[Alxe]

@AA-Turner Can I reopen this as "Warnings output after running Sphinx twice in the same process?".

I understand that you'll only support the latest release, but the exception is only one of the problems.

[AA-Turner]

Ok, but please open a new issue showing only the problems with the latest version of Sphinx.

A