8.2.0 regression: ``sphinx.ext.autosummary.get_documenter`` and ``sphinx-automodapi``

[neutrinoceros]

Describe the bug

Sphinx 8.2.0rc1 appears to crash on aImportError when trying to build astropy's documentation.
xref astropy/astropy#17785

Output

Extension error (sphinx_automodapi.automodsumm)!

Versions
========

* Platform:         linux; (Linux-5.19.0-1028-aws-x86_64-with-glibc2.35)
* Python version:   3.13.2 (CPython)
* Sphinx version:   8.2.0rc1
* Docutils version: 0.21.2
* Jinja2 version:   3.1.5
* Pygments version: 2.19.1

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

None.

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

None.

Traceback
=========

    Traceback (most recent call last):
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/events.py", line 404, in emit
        results.append(listener.handler(self.app, *args))
                       ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx_automodapi/automodsumm.py", line 308, in process_automodsumm_generation
        generate_automodsumm_docs(
        ~~~~~~~~~~~~~~~~~~~~~~~~~^
            lines, sfn, app=app, builder=app.builder,
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            base_path=app.srcdir,
            ^^^^^^^^^^^^^^^^^^^^^
            inherited_members=app.config.automodsumm_inherited_members,
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            included_members=app.config.automodsumm_included_members)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx_automodapi/automodsumm.py", line 463, in generate_automodsumm_docs
        from sphinx.ext.autosummary import import_by_name, get_documenter
    ImportError: cannot import name 'get_documenter' from 'sphinx.ext.autosummary' (/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/ext/autosummary/__init__.py)
    
    The above exception was the direct cause of the following exception:
    
    Traceback (most recent call last):
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/cmd/build.py", line 414, in build_main
        app = Sphinx(
            srcdir=args.sourcedir,
        ...<14 lines>...
            exception_on_warning=args.exception_on_warning,
        )
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/application.py", line 332, in __init__
        self._init_builder()
        ~~~~~~~~~~~~~~~~~~^^
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/application.py", line 414, in _init_builder
        self.events.emit('builder-inited')
        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
      File "/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/events.py", line 415, in emit
        raise ExtensionError(
        ...<4 lines>...
        ) from exc
    sphinx.errors.ExtensionError: Handler <function process_automodsumm_generation at 0x7f85786839c0> for event 'builder-inited' threw an exception (exception: cannot import name 'get_documenter' from 'sphinx.ext.autosummary' (/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/17785/lib/python3.13/site-packages/sphinx/ext/autosummary/__init__.py))


The full traceback has been saved in:
/tmp/sphinx-err-rzl_w6qg.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.

This looks to me like this happens because f3e0de1 madesphinx.ext.autosummary.get_documenter private, breaking sphinx-automodapi in the process.

How to Reproduce

short of a minimal reproducer (at least do now), I confirm that I'm able to reproduce the error see on ReadTheDocs locally:

git clone https://github.com/astropy/astropy
cd astropy
python -m pip install ".[docs, all]"
cd docs
python -m sphinx -T -W --keep-going -b html -d _build/doctrees -D language=en . docs-build/html

Environment Information

Platform:              darwin; (macOS-15.3-arm64-arm-64bit-Mach-O)
Python version:        3.13.2 (main, Feb  5 2025, 18:58:04) [Clang 19.1.6 ])
Python implementation: CPython
Sphinx version:        8.2.0rc1
Docutils version:      0.21.2
Jinja2 version:        3.1.5
Pygments version:      2.19.1

Sphinx extensions

Additional context

No response

[AA-Turner]

Thank you for reporting. I'm not sure we consider get_documenter to be public API (it is undocumented). What's the use case in sphinx-automodapi?

To unblock the release, I can restore a get_documenter() that raises a DeprecationWarning, but it would also be good to know what use sphinx-automodapi has for extending sphinx.ext.autosummary, and how we can better codify expectations.

A

[neutrinoceros]

get_documenter is used within a single function in sphinx-automodapi.
https://github.com/astropy/sphinx-automodapi/blob/3bd9e9c7a363b9a7646762fad29d7ab59e4766ff/sphinx_automodapi/automodsumm.py#L461

Specifically, what seems to be used is the objtype attribute on the return value, where 'module', 'class', 'method' and 'attribute' are the value that are special-cased. Is there a better way to inspect this value through public API only ?

[pllim]

Thanks, everyone!

It is unfortunate that this breaking change was done so close to cutting the RC, to the point that even that sphinx-automodapi runs against sphinx-dev, it was not caught in time.

https://github.com/astropy/sphinx-automodapi/actions/workflows/ci_workflows.yml?query=branch%3Amain -- Passed last week, only failed 9 hours ago.

[AA-Turner]

Hence why we had the release candidate! I admit I had proceeded on the basis that the implementation of autosummary was private; we don't document any of it. I have pushed 8a6663f to restore the function.

A

[pllim]

Thanks for the quick turnaround, @AA-Turner ! sphinx-automodapi existed before I was more involved in Astropy so I cannot explain why the situation is the way it is now, but I appreciate your understanding. Do you still plan to deprecate get_documenter?

[neutrinoceros]

FYI @AA-Turner astropy's doc as a whole builds correctly with rc2, no other issue to report. Thanks for your prompt response !