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
Documentation/gpu/i915.rst is not included in the TOC tree, but newer
versions of sphinx parse it anyway. That leads to this hard build failure:
> Global GTT Fence Handling
> ~~~~~~~~~~~~~~~~~~~~~~~~~
>
> reST markup error:
> /stuff/k/git/kernel/Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent:
Make the underlining consistent and restore a working docs build.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/gpu/i915.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 055df45596c1..cf9ff64753cc 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -401,13 +401,13 @@ GTT Fences and Swizzling
:internal:
Global GTT Fence Handling
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
:doc: fence register handling
Hardware Tiling and Swizzling Details
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
:doc: tiling swizzling details
--
2.21.0
Commit 13bac55ef7ae ("doc/mm: New documentation for memory performance")
added numaperf.rst, but did not add it to the TOC tree. There was also an
incorrectly marked literal block leading to this warning sequence:
numaperf.rst:24: WARNING: Unexpected indentation.
numaperf.rst:24: WARNING: Inline substitution_reference start-string without end-string.
numaperf.rst:25: WARNING: Block quote ends without a blank line; unexpected unindent.
Fix the block and add the file to the document tree.
Fixes: 13bac55ef7ae ("doc/mm: New documentation for memory performance")
Cc: Keith Busch <[email protected]>
Cc: Mike Rapoport <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/admin-guide/mm/index.rst | 1 +
Documentation/admin-guide/mm/numaperf.rst | 2 +-
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
index 8edb35f11317..ddf8d8d33377 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -31,6 +31,7 @@ the Linux memory management.
ksm
memory-hotplug
numa_memory_policy
+ numaperf
pagemap
soft-dirty
transhuge
diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst
index b79f70c04397..c067ed145158 100644
--- a/Documentation/admin-guide/mm/numaperf.rst
+++ b/Documentation/admin-guide/mm/numaperf.rst
@@ -15,7 +15,7 @@ characteristics. Some memory may share the same node as a CPU, and others
are provided as memory only nodes. While memory only nodes do not provide
CPUs, they may still be local to one or more compute nodes relative to
other nodes. The following diagram shows one such example of two compute
-nodes with local memory and a memory only node for each of compute node:
+nodes with local memory and a memory only node for each of compute node::
+------------------+ +------------------+
| Compute Node 0 +-----+ Compute Node 1 |
--
2.21.0
On Wed, May 22, 2019 at 02:50:29PM -0600, Jonathan Corbet wrote:
> Commit 13bac55ef7ae ("doc/mm: New documentation for memory performance")
> added numaperf.rst, but did not add it to the TOC tree. There was also an
> incorrectly marked literal block leading to this warning sequence:
>
> numaperf.rst:24: WARNING: Unexpected indentation.
> numaperf.rst:24: WARNING: Inline substitution_reference start-string without end-string.
> numaperf.rst:25: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Fix the block and add the file to the document tree.
>
> Fixes: 13bac55ef7ae ("doc/mm: New documentation for memory performance")
> Cc: Keith Busch <[email protected]>
> Cc: Mike Rapoport <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
Reviewed-by: Mike Rapoport <[email protected]>
> ---
> Documentation/admin-guide/mm/index.rst | 1 +
> Documentation/admin-guide/mm/numaperf.rst | 2 +-
> 2 files changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
> index 8edb35f11317..ddf8d8d33377 100644
> --- a/Documentation/admin-guide/mm/index.rst
> +++ b/Documentation/admin-guide/mm/index.rst
> @@ -31,6 +31,7 @@ the Linux memory management.
> ksm
> memory-hotplug
> numa_memory_policy
> + numaperf
> pagemap
> soft-dirty
> transhuge
> diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst
> index b79f70c04397..c067ed145158 100644
> --- a/Documentation/admin-guide/mm/numaperf.rst
> +++ b/Documentation/admin-guide/mm/numaperf.rst
> @@ -15,7 +15,7 @@ characteristics. Some memory may share the same node as a CPU, and others
> are provided as memory only nodes. While memory only nodes do not provide
> CPUs, they may still be local to one or more compute nodes relative to
> other nodes. The following diagram shows one such example of two compute
> -nodes with local memory and a memory only node for each of compute node:
> +nodes with local memory and a memory only node for each of compute node::
>
> +------------------+ +------------------+
> | Compute Node 0 +-----+ Compute Node 1 |
> --
> 2.21.0
>
--
Sincerely yours,
Mike.
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 <[email protected]> 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 <[email protected]> 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 <[email protected]> escreveu:
> On Thu, May 23, 2019 at 01:13:23PM +0300, Jani Nikula wrote:
> > On Thu, 23 May 2019, Oleksandr Natalenko <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
On Wed, May 22, 2019 at 10:51 PM Jonathan Corbet <[email protected]> wrote:
>
> Documentation/gpu/i915.rst is not included in the TOC tree, but newer
> versions of sphinx parse it anyway. That leads to this hard build failure:
It is included I think: Documentation/gpu/index.rst -> drivers.rst ->
i915.rst. With that corrected A-b: me.
btw this patch didn't go to intel-gfx and all i915 maintainers, I
think per get_maintainers.pl it should have. Just asking since I had a
few patches of my own where get_maintainers.pl didn't seem to do the
right thing somehow.
-Daniel
>
> > Global GTT Fence Handling
> > ~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > reST markup error:
> > /stuff/k/git/kernel/Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent:
>
> Make the underlining consistent and restore a working docs build.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> Documentation/gpu/i915.rst | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 055df45596c1..cf9ff64753cc 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -401,13 +401,13 @@ GTT Fences and Swizzling
> :internal:
>
> Global GTT Fence Handling
> -~~~~~~~~~~~~~~~~~~~~~~~~~
> +-------------------------
>
> .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
> :doc: fence register handling
>
> Hardware Tiling and Swizzling Details
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +-------------------------------------
>
> .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
> :doc: tiling swizzling details
> --
> 2.21.0
>
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
On Wed, 29 May 2019 08:54:16 +0200
Daniel Vetter <[email protected]> wrote:
> > Documentation/gpu/i915.rst is not included in the TOC tree, but newer
> > versions of sphinx parse it anyway. That leads to this hard build failure:
>
> It is included I think: Documentation/gpu/index.rst -> drivers.rst ->
> i915.rst. With that corrected A-b: me.
>
> btw this patch didn't go to intel-gfx and all i915 maintainers, I
> think per get_maintainers.pl it should have. Just asking since I had a
> few patches of my own where get_maintainers.pl didn't seem to do the
> right thing somehow.
It is included, just a level down and I wasn't paying attention.
In any case, this patch needs to be dropped; the kerneldoc comment
changes I sent (and Jani acked) are the better fix for this problem.
Thanks,
jon