Bug 789531 – [Tracker] Packages broken with >=dev-python/sphinx-4.0.0

• Product: Gentoo Linux
• Status: RESOLVED OBSOLETE

[Description Sam James 2021-05-11 21:19:41 UTC]

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

[Comment 1 Michał Górny 2021-05-11 22:14:55 UTC]

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.

[Comment 2 Georgy Yakovlev 2021-05-22 03:05:57 UTC]

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.

[Comment 3 Andrey Grozin 2021-05-22 14:33:08 UTC]

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?

[Comment 4 Ionen Wolkens 2021-05-26 00:55:23 UTC]

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`)

[Comment 5 Sam James 2022-03-22 00:37:46 UTC]

yep, sphinx undid it.