[PATCH v2] Documentation/sphinx: Fix Directive import error

[PATCH v2] Documentation/sphinx: Fix Directive import error

[Takashi Iwai]

The sphinx.util.compat for Directive stuff was deprecated in the
recent Sphinx version, and now we get a build error.

Let's import from the new place, docutils.parsers.rst, while keeping
the old sphinx.util.compat as fallback.

Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
v1->v2: Change the fallback order as Matthew suggested, the new one at first

 Documentation/sphinx/kerneldoc.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 39aa9e8697cc..34396976eb0a 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -37,7 +37,10 @@ import glob
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives
-from sphinx.util.compat import Directive
+try:
+    from docutils.parsers.rst import directives, Directive
+except ImportError:
+    from sphinx.util.compat import Directive
 from sphinx.ext.autodoc import AutodocReporter
 
 __version__  = '1.0'
-- 
2.16.2

Re: [PATCH v2] Documentation/sphinx: Fix Directive import error

[Jani Nikula]

On Fri, 02 Mar 2018, Takashi Iwai <tiwai@suse.de> wrote:
> The sphinx.util.compat for Directive stuff was deprecated in the
> recent Sphinx version, and now we get a build error.
>
> Let's import from the new place, docutils.parsers.rst, while keeping
> the old sphinx.util.compat as fallback.
>
> Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> Signed-off-by: Takashi Iwai <tiwai@suse.de>
> ---
> v1->v2: Change the fallback order as Matthew suggested, the new one at first

So this crossed my mind as well... and then I thought it'll probably
succeed on older Sphinx, and the fallback is not needed. The question
is, are these equal? Can we just import from docutils.parsers.rst?

I'm sorry I don't have the time to find the answers to these questions
as well. :(

BR,
Jani.


>
>  Documentation/sphinx/kerneldoc.py | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index 39aa9e8697cc..34396976eb0a 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -37,7 +37,10 @@ import glob
>  from docutils import nodes, statemachine
>  from docutils.statemachine import ViewList
>  from docutils.parsers.rst import directives
> -from sphinx.util.compat import Directive
> +try:
> +    from docutils.parsers.rst import directives, Directive
> +except ImportError:
> +    from sphinx.util.compat import Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v2] Documentation/sphinx: Fix Directive import error

[Matthew Wilcox]

On Fri, Mar 02, 2018 at 06:01:50PM +0200, Jani Nikula wrote:
> On Fri, 02 Mar 2018, Takashi Iwai <tiwai@suse.de> wrote:
> > The sphinx.util.compat for Directive stuff was deprecated in the
> > recent Sphinx version, and now we get a build error.
> >
> > Let's import from the new place, docutils.parsers.rst, while keeping
> > the old sphinx.util.compat as fallback.
> >
> > Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> > Signed-off-by: Takashi Iwai <tiwai@suse.de>
> > ---
> > v1->v2: Change the fallback order as Matthew suggested, the new one at first
> 
> So this crossed my mind as well... and then I thought it'll probably
> succeed on older Sphinx, and the fallback is not needed. The question
> is, are these equal? Can we just import from docutils.parsers.rst?

I found a github page which implies that docutils.parsers.rst.Directive
was added 12 years ago (!) so we're probably safe to rely on it:

https://github.com/docutils-mirror/docutils/commit/9649abee47b4ce4db51be1d90fcb1fb500fa78b3

Again, I'm no pythonista, so I may have muddled this.

Re: [PATCH v2] Documentation/sphinx: Fix Directive import error

[Matthew Wilcox]

On Fri, Mar 02, 2018 at 08:42:54AM -0800, Matthew Wilcox wrote:
> On Fri, Mar 02, 2018 at 06:01:50PM +0200, Jani Nikula wrote:
> > On Fri, 02 Mar 2018, Takashi Iwai <tiwai@suse.de> wrote:
> > > The sphinx.util.compat for Directive stuff was deprecated in the
> > > recent Sphinx version, and now we get a build error.
> > >
> > > Let's import from the new place, docutils.parsers.rst, while keeping
> > > the old sphinx.util.compat as fallback.
> > >
> > > Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> > > Signed-off-by: Takashi Iwai <tiwai@suse.de>
> > > ---
> > > v1->v2: Change the fallback order as Matthew suggested, the new one at first
> > 
> > So this crossed my mind as well... and then I thought it'll probably
> > succeed on older Sphinx, and the fallback is not needed. The question
> > is, are these equal? Can we just import from docutils.parsers.rst?
> 
> I found a github page which implies that docutils.parsers.rst.Directive
> was added 12 years ago (!) so we're probably safe to rely on it:
> 
> https://github.com/docutils-mirror/docutils/commit/9649abee47b4ce4db51be1d90fcb1fb500fa78b3
> 
> Again, I'm no pythonista, so I may have muddled this.

I spent some time delving through the Sphinx codebase.  The compat
version was added so you could use Directive with docutils 0.4 onwards.
docutils 0.5 onwards has Directive.  So as long as we're comfortable
mandating docutils from 2009, we're fine ;-)

Re: [PATCH v2] Documentation/sphinx: Fix Directive import error

[Matthew Wilcox]

On Fri, Mar 02, 2018 at 04:28:31PM +0100, Takashi Iwai wrote:
>  from docutils.parsers.rst import directives
> -from sphinx.util.compat import Directive
> +try:
> +    from docutils.parsers.rst import directives, Directive

We also don't need 'directives' on this line as it was imported on the
previous line.

> +except ImportError:
> +    from sphinx.util.compat import Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'

Here's what I tested on Debian:

+++ b/Documentation/sphinx/kerneldoc.py
@@ -37,7 +37,10 @@ import glob
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives
-from sphinx.util.compat import Directive
+try:
+    from docutils.parsers.rst import Directive
+except ImportError:
+    from sphinx.util.compat import Directive
 from sphinx.ext.autodoc import AutodocReporter
 
 __version__  = '1.0'

[PATCH v3] Documentation/sphinx: Fix Directive import error

[Matthew Wilcox]

From: Matthew Wilcox <mawilcox@microsoft.com>

Sphinx 1.7 removed sphinx.util.compat.Directive so people
who have upgraded cannot build the documentation.  Switch to
docutils.parsers.rst.Directive which has been available since
docutils 0.5 released in 2009.

Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
Co-developed-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 39aa9e8697cc..fbedcc39460b 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -36,8 +36,7 @@ import glob
 
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
-from docutils.parsers.rst import directives
-from sphinx.util.compat import Directive
+from docutils.parsers.rst import directives, Directive
 from sphinx.ext.autodoc import AutodocReporter
 
 __version__  = '1.0'

Re: [PATCH v3] Documentation/sphinx: Fix Directive import error

[Jani Nikula]

On Fri, 02 Mar 2018, Matthew Wilcox <willy@infradead.org> wrote:
> From: Matthew Wilcox <mawilcox@microsoft.com>
>
> Sphinx 1.7 removed sphinx.util.compat.Directive so people
> who have upgraded cannot build the documentation.  Switch to
> docutils.parsers.rst.Directive which has been available since
> docutils 0.5 released in 2009.
>
> Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> Co-developed-by: Takashi Iwai <tiwai@suse.de>
> Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>

I think this is the best approach.

FWIW,

Acked-by: Jani Nikula <jani.nikula@intel.com>

>
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index 39aa9e8697cc..fbedcc39460b 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -36,8 +36,7 @@ import glob
>  
>  from docutils import nodes, statemachine
>  from docutils.statemachine import ViewList
> -from docutils.parsers.rst import directives
> -from sphinx.util.compat import Directive
> +from docutils.parsers.rst import directives, Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v3] Documentation/sphinx: Fix Directive import error

[Jonathan Corbet]

On Fri, 2 Mar 2018 10:40:14 -0800
Matthew Wilcox <willy@infradead.org> wrote:

> Sphinx 1.7 removed sphinx.util.compat.Directive so people
> who have upgraded cannot build the documentation.  Switch to
> docutils.parsers.rst.Directive which has been available since
> docutils 0.5 released in 2009.
> 
> Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> Co-developed-by: Takashi Iwai <tiwai@suse.de>
> Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>

FWIW, I've *finally* gotten a chance to test this with a few sphinx
versions; it works just fine, of course.  Will get it upstream shortly.

Thanks,

jon