Re: [PATCH RFC 0/2] docs: Deal with some Sphinx deprecation warnings

[Markus Heiser <markus.heiser@darmarit.de>]

22.05.19 um 12:19 schrieb Mauro Carvalho Chehab:
> Em Wed, 22 May 2019 10:36:45 +0300
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> 
>> On Tue, 21 May 2019, Jonathan Corbet <corbet@lwn.net> wrote:
>>> The Sphinx folks are deprecating some interfaces in the upcoming 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.
>>
>> Frankly, I'd just require Sphinx 1.7+, available even in Debian stable
>> through stretch-backports.
> 
> We can raise the bar and force a 1.7 or even 1.8 (Fedora 30 comes
> with version 1.8.4), but I would prefer to keep support older versions,
> at least while we don't depend on some new features introduced after
> the version we're using, and while our extensions won't require a major
> rework due to a new version.

Lets use 1.7 :

- no need for Use_SSI wrapper
- new log should work with 1.7 [1] --> no need for kernellog.py and
   additional imports, instead include on top of python modules ::

     from sphinx.util import logging
     logger = logging.getLogger('kerneldoc')

[1] 
https://github.com/sphinx-doc/sphinx/commit/6d4e6454093953943e79d4db6efeb17390870e62


BTW we can drop other (old) sphinx-version issues e.g.
Documentation/conf.py  which fails with version 2.0:

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 72647a38b5c2..ba82715b6715 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,13 +34,7 @@ needs_sphinx = '1.3'
  # Add any Sphinx extension module names here, as strings. They can be
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  # ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 
'kfigure', 'sphinx.ext.ifconfig']
-
-# The name of the math extension changed on Sphinx 1.4
-if major == 1 and minor > 3:
-    extensions.append("sphinx.ext.imgmath")
-else:
-    extensions.append("sphinx.ext.pngmath")
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 
'kfigure', 'sphinx.ext.ifconfig', 'sphinx.ext.imgmath']

  # Add any paths that contain templates here, relative to this directory.
  templates_path = ['_templates']

-- Markus --