Custom configuration classes break numpydoc

[tacaswell]

Describe the bug

#13783 changes the type of the configuration passed to extensions from (I assume) a dict to a custom class. numpy doc has code that looks like

def mangle_docstrings(app: SphinxApp, what, name, obj, options, lines):
    if DEDUPLICATION_TAG in lines:
        return
    show_inherited_class_members = app.config.numpydoc_show_inherited_class_members
    if isinstance(show_inherited_class_members, dict):
        try:
            show_inherited_class_members = show_inherited_class_members[name]
        except KeyError:
            show_inherited_class_members = True

    cfg = {
        "use_plots": app.config.numpydoc_use_plots,
        "show_class_members": app.config.numpydoc_show_class_members,
        "show_inherited_class_members": show_inherited_class_members,
        "class_members_toctree": app.config.numpydoc_class_members_toctree,
        "attributes_as_param_list": app.config.numpydoc_attributes_as_param_list,
        "xref_param_type": app.config.numpydoc_xref_param_type,
        "xref_aliases": app.config.numpydoc_xref_aliases_complete,
        "xref_ignore": app.config.numpydoc_xref_ignore,
    }
    cfg.update(options or {})  # <- fails with "NoneType not callable"

The source of the problem is that because _AutoDocumenterOptions returns None for any missing attribute Python tries to call options.items() which in turn fails with the very confusing error :

Extension error (numpydoc.numpydoc)!

Versions
========

* Platform:         linux; (Linux-6.16.7-arch1-1-x86_64-with-glibc2.42)
* Python version:   3.15.0a0 (CPython)
* Sphinx version:   8.3.0
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.18.0

Last Messages
=============


    reading sources... [  3%]
    _tags/topic-tagging


    reading sources... [  4%]
    api/_afm_api

    Path to light image logo does not exist: _static/logo_light.svg
    Path to dark image logo does not exist: _static/logo_dark.svg

Loaded Extensions
=================

* sphinx.ext.mathjax (8.3.0)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* sphinx.ext.autodoc.preserve_defaults (8.3.0)
* sphinx.ext.autodoc.type_comment (8.3.0)
* sphinx.ext.autodoc.typehints (8.3.0)
* sphinx.ext.autodoc (8.3.0)
* sphinx.ext.autosummary (8.3.0)
* sphinx.ext.graphviz (8.3.0)
* sphinx.ext.inheritance_diagram (8.3.0)
* sphinx.ext.intersphinx (8.3.0)
* sphinx.ext.ifconfig (8.3.0)
* IPython.sphinxext.ipython_console_highlighting (unknown version)
* IPython.sphinxext.ipython_directive (unknown version)
* numpydoc (1.10.0rc0.dev0)
* sphinx_gallery.gen_gallery (0.19.0)
* matplotlib.sphinxext.mathmpl (unknown version)
* matplotlib.sphinxext.plot_directive (3.11.0.dev1414+g5e621a4018.d20251010)
* matplotlib.sphinxext.roles (3.11.0.dev1414+g5e621a4018.d20251010)
* matplotlib.sphinxext.figmpl_directive (3.11.0.dev1414+g5e621a4018.d20251010)
* sphinxext.github (unknown version)
* sphinxext.math_symbol_table (unknown version)
* sphinxext.missing_references (unknown version)
* sphinxext.mock_gui_toolkits (unknown version)
* sphinxext.skip_deprecated (unknown version)
* sphinxext.redirect_from (unknown version)
* sphinx_copybutton (0.5.2)
* sphinx_design (0.6.0)
* sphinx_tags (0.4)
* sphinx.ext.linkcode (8.3.0)
* sphinxcontrib.video (unknown version)
* mpl_sphinx_theme (3.9.0)
* pydata_sphinx_theme (unknown version)

Traceback
=========

      File "/home/tcaswell/.virtualenvs/cp315/lib/python3.15/site-packages/sphinx/events.py", line 423, in emit
        raise ExtensionError(
        ...<4 lines>...
        ) from exc
    sphinx.errors.ExtensionError: Handler <function mangle_docstrings at 0x7f46477a8720> for event 'autodoc-process-docstring' threw an exception (exception: 'NoneType' object is not callable)


The full traceback has been saved in:
/tmp/sphinx-err-6obaxjdt.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
make: *** [Makefile:50: html] Error 2

How to Reproduce

I hit this trying to build the Matplotlib docs, I apologize for not having a simpler reproducer.

Environment Information

Platform:              linux; (Linux-6.16.7-arch1-1-x86_64-with-glibc2.42)
Python version:        3.15.0a0 (heads/main:03f5519d776, Aug 15 2025, 14:41:31) [GCC 15.2.1 20250813])
Python implementation: CPython
Sphinx version:        8.3.0  # master branch @ ad3f3cc062
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.18.0

Sphinx extensions

Additional context

No response

[AA-Turner]

@tacaswell Apologies for missing this report, @Carreau pointed it out just now.

Is numpydoc able to use something like the following?:

if options:
    cfg.update({k.replace('_', '-'): v for k, v in vars(options).items()})

Previously, autodoc used the Options class, a dict subclass that supported attribute access:

sphinx/sphinx/ext/autodoc/_legacy_class_based/_directive_options.py

Lines 90 to 100 in 28c31aa

	class Options(dict[str, Any]): # NoQA: FURB189
	"""A dict/attribute hybrid that returns None on nonexisting keys."""
	def copy(self) -> Options:
	return Options(super().copy())
	def __getattr__(self, name: str) -> Any:
	try:
	return self[name.replace('_', '-')]
	except KeyError:
	return None

Now, we use the _AutodocDocumenterOptions object:

sphinx/sphinx/ext/autodoc/_directive_options.py

Line 45 in 28c31aa

class _AutoDocumenterOptions:

The docs have always (since 2008!) said that options is attribute access, but the old dict-subclass approach meant that index-access was implicitly supported.

Would it be worth adding __getitem__() to _AutodocDocumenterOptions and going through a deprecation cycle?

A