sphinx 9 build errors

[doronbehar]

When trying to build man page with sphinx 9, I get:

Versions
========

* Platform:         linux; (Linux-6.18.19-x86_64-with-glibc2.42)
* Python version:   3.13.12 (CPython)
* Sphinx version:   9.1.0
* Docutils version: 0.22.4
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

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

    [AutoAPI] Adding AutoAPI TOCTree [autoapi/index] to index.rst
    reading sources... [ 81%]
    indices

    reading sources... [ 85%]
    man

    reading sources... [ 89%]
    man/khard

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

* sphinx.ext.mathjax (9.1.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 (9.1.0)
* sphinx.ext.autosummary (9.1.0)
* sphinx.ext.graphviz (9.1.0)
* sphinx.ext.inheritance_diagram (9.1.0)
* autoapi.extension (unknown version)
* sphinx.ext.autosectionlabel (9.1.0)
* sphinx.ext.todo (9.1.0)
* sphinx_autodoc_typehints (unknown version)
* sphinxarg.ext (0.5.2)

Traceback
=========

    Traceback (most recent call last):
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/cmd/build.py", line 432, in build_main
        app.build(args.force_all, args.filenames)
        ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/application.py", line 442, in build
        self.builder.build_update()
        ~~~~~~~~~~~~~~~~~~~~~~~~~^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 378, in build_update
        self.build(['__all__'], summary=to_build, method='update')
        ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 409, in build
        updated_docnames = set(self.read())
                               ~~~~~~~~~^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 525, in read
        self._read_serial(docnames)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 590, in _read_serial
        self.read_doc(docname)
        ~~~~~~~~~~~~~^^^^^^^^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 653, in read_doc
        doctree = _parse_str_to_doctree(
            content,
        ...<6 lines>...
            transforms=self._registry.get_transforms(),
        )
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/util/docutils.py", line 902, in _parse_str_to_doctree
        parser.parse(content, document)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
      File "/nix/store/4rkpcf7dbam7921pvpfvdwyz1305qy5s-python3.13-sphinx-9.1.0/lib/python3.13/site-packages/sphinx/parsers.py", line 99, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 182, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/statemachine.py", line 234, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/statemachine.py", line 446, in check_line
        return method(match, context, next_state)
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2487, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2499, in explicit_construct
        return method(self, expmatch)
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2236, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/nix/store/pmjzp87gfd5fpzsc51ikdrxgf59a0dli-python3.13-docutils-0.22.4/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2286, in run_directive
        result = directive_instance.run()
      File "/nix/store/kpqqcvd5sspdi86yj39jfpk1ffsdglc9-python3.13-sphinx-argparse-0.5.2/lib/python3.13/site-packages/sphinxarg/ext.py", line 511, in run
        with mock(self.config.autodoc_mock_imports):
             ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    TypeError: 'module' object is not callable

[lucc]

Thanks for the report. This is an upstream bug that has been reported in several issues:

• Issues with Sphinx 9.0.1 (importing mock from autodoc) sphinx-doc/sphinx-argparse#82
• sphinx 9.0.4 breaks build of khard 0.20.0 sphinx-doc/sphinx#14206
• Unexpected results in importing mock from autodoc sphinx-doc/sphinx#14333

Our CI here is also failing because of that. I am still waiting for the upstream fix.

[lucc]

I decided to drop the autodoc typehints extension from the sphinx build as it has little/no(?) impact on the docs.

Downstream could cherry pick 4e07412 if they want the fix before the next release.

[doronbehar]

@lucc I don't think it is worth the effort, but apparently this could have been an alternative solution path:

diff '--color=auto' -u -r khard-0.20.1/doc/source/conf.py new/doc/source/conf.py
--- khard-0.20.1/doc/source/conf.py	2025-07-29 04:47:18.000000000 +0800
+++ new/doc/source/conf.py	2026-03-29 12:53:42.904389827 +0800
@@ -52,8 +52,8 @@
     'sphinx.ext.autodoc',  # https://pypi.org/project/sphinx-autodoc-typehints/
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',
-    'sphinx_autodoc_typehints',  # https://pypi.org/project/sphinx-autodoc-typehints/
     'sphinxarg.ext',
+    'sphinx_autodoc_typehints',  # https://pypi.org/project/sphinx-autodoc-typehints/
 ]
 
 autoapi_type = 'python'

Per sphinx-doc/sphinx#14333 (comment) .

[lucc]

@doronbehar the comment you are linking is mine, so yes I now that but I compared the html output with and without the extension and did not see any relevant change. So I ditched the dependency.