| Message ID | 20190522205034.25724-1-corbet@lwn.net |
|---|---|
| Headers | show |
| Series | docs: Fixes for recent versions of Sphinx | expand |
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
On Thu, 23 May 2019, Oleksandr Natalenko <oleksandr@redhat.com> wrote: > 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. Please share your Sphinx version (sphinx-build --version). BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center
On Thu, May 23, 2019 at 01:13:23PM +0300, Jani Nikula wrote: > On Thu, 23 May 2019, Oleksandr Natalenko <oleksandr@redhat.com> wrote: > > 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. > > Please share your Sphinx version (sphinx-build --version). [~]$ sphinx-build --version sphinx-build 2.0.1 -- Best regards, Oleksandr Natalenko (post-factum) Senior Software Maintenance Engineer
Em Thu, 23 May 2019 12:15:34 +0200 Oleksandr Natalenko <oleksandr@redhat.com> escreveu: > On Thu, May 23, 2019 at 01:13:23PM +0300, Jani Nikula wrote: > > On Thu, 23 May 2019, Oleksandr Natalenko <oleksandr@redhat.com> wrote: > > > 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. > > > > Please share your Sphinx version (sphinx-build --version). > > [~]$ sphinx-build --version > sphinx-build 2.0.1 > Same here with vanilla 2.0.0 (installed via pip3): Running Sphinx v2.0.0 /devel/v4l/docs/Documentation/sphinx/cdomain.py:51: RemovedInSphinx30Warning: app.override_domain() is deprecated. Use app.add_domain() with override option instead. app.override_domain(CDomain) It seems that this message is there since 1.8: https://www.sphinx-doc.org/en/1.8/_modules/sphinx/application.html The fix seems to be trivial: just replace it to: app.add_domain(domain, override=True) Thanks, Mauro
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 Thanks, Mauro
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
On Thu, 23 May 2019 07:38:30 -0300 Mauro Carvalho Chehab <mchehab@kernel.org> wrote: > It seems that this message is there since 1.8: > > https://www.sphinx-doc.org/en/1.8/_modules/sphinx/application.html ...which is strange, since I didn't see it until I built with 2.0. It was annoying to see a new warning, but I figured we had some time still before needing to rush out a last-minute fix for that one :) jon