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

Oleksandr Natalenko
2019-05-23T11:22:48Z

On Thu, May 23, 2019 at 07:45:45AM -0300, Mauro Carvalho Chehab wrote:
> Em Thu, 23 May 2019 11:39:44 +0200
> Oleksandr Natalenko <oleksandr@redhat.com> escreveu:
>
> > 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.
> >
>
> Just sent a fix. Could you please test?
>
>
> https://lore.kernel.org/lkml/b38a9fdfdcda49b2c6118072afac564e96406800.1558608217.git.mchehab+samsung@kernel.org/T/#u

Yes, now it's fine. Thanks.

>
> Thanks,
> Mauro

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