Re: [PATCH 0/8] docs: Fixes for recent versions of Sphinx

Oleksandr Natalenko
2019-05-23T09:39:49Z

Hi.

On Wed, May 22, 2019 at 02:50:26PM -0600, Jonathan Corbet wrote:
> The Sphinx folks deprecated some interfaces in the 2.0 release; one
> immediate result of that is a bunch of warnings that show up when building
> with 1.8. These two patches make those warnings go away, but at a cost:
>
> - It introduces a couple of Sphinx version checks, which are always
> ugly, but the alternative would be to stop supporting versions
> before 1.7. For now, I think we can carry that cruft.
>
> - The second patch causes the build to fail horribly on newer
> Sphinx installations. The change to switch_source_input() seems
> to make the parser much more finicky, increasing warnings and
> eventually failing the build altogether. In particular, it will
> scream about problems in .rst files that are not included in the
> TOC tree at all.
>
> This version of the patch set fixes up the worst problems (the i915 error
> in particular, which breaks the build hard). I've tested it with versions
> 1.4, 1.8, and 2.0.
>
> Given that these problems are already breaking builds on some systems, I
> think I may try to sell these changes to Linus for 5.2 still.
>
> Changes since v1:
> - Fix up a couple of logging changes I somehow missed
> - Don't save state when using switch_source_input()
> - Fix a few build errors
> - Add Mauro's sphinx-pre-install improvements
>
> Jonathan Corbet (7):
> doc: Cope with Sphinx logging deprecations
> doc: Cope with the deprecation of AutoReporter
> docs: fix numaperf.rst and add it to the doc tree
> lib/list_sort: fix kerneldoc build error
> docs: fix multiple doc build warnings in enumeration.rst
> docs/gpu: fix a documentation build break in i915.rst
> docs: Fix conf.py for Sphinx 2.0
>
> Mauro Carvalho Chehab (1):
> scripts/sphinx-pre-install: make it handle Sphinx versions
>
> Documentation/admin-guide/mm/index.rst | 1 +
> Documentation/admin-guide/mm/numaperf.rst | 2 +-
> Documentation/conf.py | 2 +-
> .../firmware-guide/acpi/enumeration.rst | 2 +-
> Documentation/gpu/i915.rst | 4 +-
> Documentation/sphinx/kerneldoc.py | 44 +++++++---
> Documentation/sphinx/kernellog.py | 28 +++++++
> Documentation/sphinx/kfigure.py | 40 +++++----
> lib/list_sort.c | 3 +-
> scripts/sphinx-pre-install | 81 +++++++++++++++++--
> 10 files changed, 166 insertions(+), 41 deletions(-)
> create mode 100644 Documentation/sphinx/kernellog.py
>
> --
> 2.21.0
>

Thanks for the efforts. I've run this on top of Linus' tree, and the
only sphinx-related deprecation warning I've spotted is this one:

/home/onatalen/work/src/linux/Documentation/sphinx/cdomain.py:51: RemovedInSphinx30Warning: app.override_domain() is deprecated. Use app.add_domain() with override option instead.
app.override_domain(CDomain)

Otherwise, it builds.

--
Best regards,
Oleksandr Natalenko (post-factum)
Senior Software Maintenance Engineer