Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Thu, 23 May 2019 11:39:44 +0200
From:   Oleksandr Natalenko <oleksandr@redhat.com>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Jani Nikula <jani.nikula@linux.intel.com>,
        Markus Heiser <markus.heiser@darmarit.de>,
        Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: Re: [PATCH 0/8] docs: Fixes for recent versions of Sphinx
Message-ID: <20190523093944.mylk5l3ginkpelfi@butterfly.localdomain>
References: <20190522205034.25724-1-corbet@lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190522205034.25724-1-corbet@lwn.net>
User-Agent: NeoMutt/20180716
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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