Incompatible changes from the release notes [0]: >* #8539: autodoc: info-field-list is generated into the class description when > ``autodoc_typehints='description'`` and ``autoclass_content='class'`` set >* #8898: extlinks: "%s" becomes required keyword in the link caption string >* domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate > methods that must be overrided in the concrete classes >* #4826: py domain: The structure of python objects is changed. A boolean value > is added to indicate that the python object is canonical one >* #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom > MathJax configuration may have to set the old MathJax path or update their > configuration for version 3. See :mod:`sphinx.ext.mathjax`. >* #7784: i18n: The msgid for alt text of image is changed >* #5560: napoleon: :confval:`napoleon_use_param` also affect "other parameters" > section >* #7996: manpage: Make a section directory on build manpage by default (see > :confval:`man_make_section_directory`) >* #7849: html: Change the default setting of > :confval:`html_codeblock_linenos_style` to ``'inline'`` >* #8380: html search: search results are wrapped with ``<p>`` instead of > ``<div>`` >* html theme: Move a script tag for documentation_options.js in > basic/layout.html to ``script_files`` variable >* html theme: Move CSS tags in basic/layout.html to ``css_files`` variable >* #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older >* #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese > documents >* #5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create > cross-references >* #4550: The ``align`` attribute of ``figure`` and ``table`` nodes becomes > ``None`` by default instead of ``'default'`` >* #8769: LaTeX refactoring: split sphinx.sty into multiple files and rename > some auxiliary files created in ``latex`` build output repertory >* #8937: Use explicit title instead of <no title> >* #8487: The :file: option for csv-table directive now recognizes an absolute > path as a relative path from source directory In particular: >>* #7996: manpage: Make a section directory on build manpage by default (see > :confval:`man_make_section_directory`) seems to be the most prominent issue in ebuilds so far. [0] https://github.com/sphinx-doc/sphinx/blob/96dbe5e3549815409450588b50f52da4d6aaba5e/CHANGES#L110
Ehh, great. Part of me says we should mask the new version... but then, probably no progress will be done until we unmask it again. I guess setting <sphinx-4 deps for now should suffice.
echo 'man_make_section_directory = False' >> doc/conf.py || die or something like that usually helps without need to introduce version caps. man_make_section_directory setting is backwards-compatible with older sphinx so it's safe to add it to conf.py unconditionally without checking which version of sphinx is used.
People are fixing this man/#/foo.# on a package-by-package basis (I've just done bpython). Wouldn't it be much better to fix the eclass so that it tries to install man pages from the new man/#/foo.#, and failing that, falls back to the old man/foo.# scheme?
Release 4.0.2 (released May 20, 2021) ===================================== [...] * #9217: manpage: Stop creating a section directory on build manpage by default (see :confval:`man_make_section_directory`)
yep, sphinx undid it.