TypeError encountered in extlinks.py

[aburrell]

Describe the bug

In Sphinx 6.1.1 (works fine in 5.3.0 and 4.0.3), a TypeError is raised on line 103 of sphinx/ext/extlinks.py when building documentation. The error occurs here: https://github.com/aburrell/apexpy/actions/runs/3850865270/jobs/6561478581#step:5:59

How to Reproduce

Using the docs from: https://github.com/aburrell/apexpy, run: sphinx-build -E -b html docs dist/docs from the home directory of that project. This was tested with Python 3.9 on Ubuntu (ubuntu-latest, GitHub Actions).

Environment Information

Don't know how to access the error log, but here's the output:

Running Sphinx v6.1.1
making output directory... done
[autosummary] generating autosummary for: api.rst, authors.rst, changelog.rst, contributing.rst, ex_index.rst, examples/ex_apexh.rst, examples/ex_cli.rst, examples/ex_gc.rst, examples/ex_init.rst, index.rst, installation.rst, maintenance.rst, readme.rst
[AutoAPI] Reading files... [ 11%] /home/runner/work/apexpy/apexpy/apexpy/__init__.py
[AutoAPI] Reading files... [ 22%] /home/runner/work/apexpy/apexpy/apexpy/__main__.py
[AutoAPI] Reading files... [ 33%] /home/runner/work/apexpy/apexpy/apexpy/_gcc_build_bitness.py
[AutoAPI] Reading files... [ 44%] /home/runner/work/apexpy/apexpy/apexpy/apex.py
[AutoAPI] Reading files... [ 55%] /home/runner/work/apexpy/apexpy/apexpy/helpers.py
[AutoAPI] Reading files... [ 66%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_Apex.py
[AutoAPI] Reading files... [ 77%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_fortranapex.py
[AutoAPI] Reading files... [ 88%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_cmd.py
[AutoAPI] Reading files... [100%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_helpers.py

[AutoAPI] Mapping Data... [ 11%] /home/runner/work/apexpy/apexpy/apexpy/__init__.py
[AutoAPI] Mapping Data... [ 22%] /home/runner/work/apexpy/apexpy/apexpy/__main__.py
[AutoAPI] Mapping Data... [ 33%] /home/runner/work/apexpy/apexpy/apexpy/_gcc_build_bitness.py
[AutoAPI] Mapping Data... [ 44%] /home/runner/work/apexpy/apexpy/apexpy/apex.py
[AutoAPI] Mapping Data... [ 55%] /home/runner/work/apexpy/apexpy/apexpy/helpers.py
[AutoAPI] Mapping Data... [ 66%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_Apex.py
[AutoAPI] Mapping Data... [ 77%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_fortranapex.py
[AutoAPI] Mapping Data... [ 88%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_cmd.py
[AutoAPI] Mapping Data... [100%] /home/runner/work/apexpy/apexpy/apexpy/tests/test_helpers.py

[AutoAPI] Rendering Data... [ 11%] apexpy
[AutoAPI] Rendering Data... [ 22%] apexpy.__main__
[AutoAPI] Rendering Data... [ 33%] apexpy._gcc_build_bitness
[AutoAPI] Rendering Data... [ 44%] apexpy.apex
[AutoAPI] Rendering Data... [ 55%] apexpy.helpers
[AutoAPI] Rendering Data... [ 66%] test_Apex
[AutoAPI] Rendering Data... [ 77%] test_fortranapex
[AutoAPI] Rendering Data... [ 88%] test_cmd
[AutoAPI] Rendering Data... [100%] test_helpers

building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 13 source files that are out of date
updating environment: [new config] 23 added, 0 changed, 0 removed
reading sources... [  4%] api

Exception occurred:
  File "/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/site-packages/sphinx/ext/extlinks.py", line 103, in role
    title = caption % part
TypeError: not all arguments converted during string formatting
The full traceback has been saved in /tmp/sphinx-err-gbrkq2pv.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Error: Process completed with exit code 2.

[AA-Turner]

EDIT

This was removed in #10471, though you should have seen warnings (permalink from the commit before removal of the functionality):

sphinx/sphinx/ext/extlinks.py

Lines 87 to 101 in 7e68154

	try:
	base_url % 'dummy'
	except (TypeError, ValueError):
	logger.warn(__('extlinks: Sphinx-6.0 will require base URL to '
	'contain exactly one \'%s\' and all other \'%\' need '
	'to be escaped as \'%%\'.')) # RemovedInSphinx60Warning
	base_url = base_url.replace('%', '%%') + '%s'
	if caption is not None:
	try:
	caption % 'dummy'
	except (TypeError, ValueError):
	logger.warning(__('extlinks: Sphinx-6.0 will require a caption string to '
	'contain exactly one \'%s\' and all other \'%\' need '
	'to be escaped as \'%%\'.')) # RemovedInSphinx60Warning
	caption = caption.replace('%', '%%') + '%s'

To fix the error, ensure that there is a single %s in both fields, or that they are None. For example, change

extlinks = {"pypi": ("https://pypi.org/project/%s", "")}

to

extlinks = {"pypi": ("https://pypi.org/project/%s", "%s")}

or

extlinks = {"pypi": ("https://pypi.org/project/%s", None)}

Please also see the documentation for help: https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

A

[aburrell]

Following the instructions I changed extlinks = {'doi': ('http://dx.doi.org/%s', 'doi:')} to extlinks = {'doi': ('http://dx.doi.org/%s', 'doi:%s')} in my conf.py. It may be worth updating the TypeError message to point users to potential issues with their conf.py file extlinks formats.

[AA-Turner]

Closing this as it was an intended change, please comment if there are further issues that are not solved by the suggested changes above.

A