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

[Markus Heiser]

22.05.19 um 12:19 schrieb Mauro Carvalho Chehab:
> Em Wed, 22 May 2019 10:36:45 +0300
> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:
>
> > On Tue, 21 May 2019, Jonathan Corbet <corbet@xxxxxxx> 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 --