[ovs-dev] doc: fix doc build when not using ovs theme

Message ID 20170417153626.7976-1-mthode@mthode.org
State Accepted
Headers show

Commit Message

Ed Swierk via dev April 17, 2017, 3:36 p.m.
Fixes the following warning.

WARNING: 'default' html theme has been renamed to 'classic'. Please change your
html_theme setting either to the new 'alabaster' default theme, or to 'classic'
to keep using the old default.

As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520

Signed-off-by: Matthew Thode <mthode@mthode.org>
---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Ben Pfaff April 17, 2017, 4:20 p.m. | #1
On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via dev wrote:
> Fixes the following warning.
> 
> WARNING: 'default' html theme has been renamed to 'classic'. Please change your
> html_theme setting either to the new 'alabaster' default theme, or to 'classic'
> to keep using the old default.
> 
> As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520
> 
> Signed-off-by: Matthew Thode <mthode@mthode.org>

Thanks.  Do you know whether this is going to break the docs build for
people with older sphinx?  That is, was "classic" introduced in sphinx
sometime after 1.1 (since that's the current minimum version for OVS)?
Ed Swierk via dev April 17, 2017, 4:32 p.m. | #2
On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via dev wrote:
>> Fixes the following warning.
>>
>> WARNING: 'default' html theme has been renamed to 'classic'. Please change your
>> html_theme setting either to the new 'alabaster' default theme, or to 'classic'
>> to keep using the old default.
>>
>> As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520
>>
>> Signed-off-by: Matthew Thode <mthode@mthode.org>
> 
> Thanks.  Do you know whether this is going to break the docs build for
> people with older sphinx?  That is, was "classic" introduced in sphinx
> sometime after 1.1 (since that's the current minimum version for OVS)?
> 
I'm not sure, the oldest version we have is 1.11.0, and the oldest
stable version we support is 2.5.0.  This is the first I've seen this
bug reported though.
Ben Pfaff April 17, 2017, 4:42 p.m. | #3
On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
> On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> > On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via dev wrote:
> >> Fixes the following warning.
> >>
> >> WARNING: 'default' html theme has been renamed to 'classic'. Please change your
> >> html_theme setting either to the new 'alabaster' default theme, or to 'classic'
> >> to keep using the old default.
> >>
> >> As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520
> >>
> >> Signed-off-by: Matthew Thode <mthode@mthode.org>
> > 
> > Thanks.  Do you know whether this is going to break the docs build for
> > people with older sphinx?  That is, was "classic" introduced in sphinx
> > sometime after 1.1 (since that's the current minimum version for OVS)?
> > 
> I'm not sure, the oldest version we have is 1.11.0, and the oldest
> stable version we support is 2.5.0.  This is the first I've seen this
> bug reported though.

I guess that you are talking about OVS versions, but I'm asking about
Sphinx versions.  Does that make any difference?  I don't know Sphinx
well at all.
Ed Swierk via dev April 17, 2017, 4:47 p.m. | #4
On 04/17/2017 11:42 AM, Ben Pfaff wrote:
> On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
>> On 04/17/2017 11:20 AM, Ben Pfaff wrote:
>>> On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via dev wrote:
>>>> Fixes the following warning.
>>>>
>>>> WARNING: 'default' html theme has been renamed to 'classic'. Please change your
>>>> html_theme setting either to the new 'alabaster' default theme, or to 'classic'
>>>> to keep using the old default.
>>>>
>>>> As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520
>>>>
>>>> Signed-off-by: Matthew Thode <mthode@mthode.org>
>>>
>>> Thanks.  Do you know whether this is going to break the docs build for
>>> people with older sphinx?  That is, was "classic" introduced in sphinx
>>> sometime after 1.1 (since that's the current minimum version for OVS)?
>>>
>> I'm not sure, the oldest version we have is 1.11.0, and the oldest
>> stable version we support is 2.5.0.  This is the first I've seen this
>> bug reported though.
> 
> I guess that you are talking about OVS versions, but I'm asking about
> Sphinx versions.  Does that make any difference?  I don't know Sphinx
> well at all.
> 
I was talking about OVS versions.  This code change only changes
anything if sphinx is not installed.

try:
    import ovs_sphinx_theme
    use_ovs_theme = True
except ImportError:
    print("Cannot find 'ovs_sphinx' package. Falling back to default
theme.")
    use_ovs_theme = False

then

if use_ovs_theme:
    html_theme = 'ovs'
else:
    html_theme = 'default'
Ben Pfaff April 17, 2017, 5:21 p.m. | #5
On Mon, Apr 17, 2017 at 11:47:30AM -0500, Matthew Thode wrote:
> On 04/17/2017 11:42 AM, Ben Pfaff wrote:
> > On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
> >> On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> >>> On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via dev wrote:
> >>>> Fixes the following warning.
> >>>>
> >>>> WARNING: 'default' html theme has been renamed to 'classic'. Please change your
> >>>> html_theme setting either to the new 'alabaster' default theme, or to 'classic'
> >>>> to keep using the old default.
> >>>>
> >>>> As reported by https://bugs.gentoo.org/show_bug.cgi?id=614520
> >>>>
> >>>> Signed-off-by: Matthew Thode <mthode@mthode.org>
> >>>
> >>> Thanks.  Do you know whether this is going to break the docs build for
> >>> people with older sphinx?  That is, was "classic" introduced in sphinx
> >>> sometime after 1.1 (since that's the current minimum version for OVS)?
> >>>
> >> I'm not sure, the oldest version we have is 1.11.0, and the oldest
> >> stable version we support is 2.5.0.  This is the first I've seen this
> >> bug reported though.
> > 
> > I guess that you are talking about OVS versions, but I'm asking about
> > Sphinx versions.  Does that make any difference?  I don't know Sphinx
> > well at all.
> > 
> I was talking about OVS versions.  This code change only changes
> anything if sphinx is not installed.
> 
> try:
>     import ovs_sphinx_theme
>     use_ovs_theme = True
> except ImportError:
>     print("Cannot find 'ovs_sphinx' package. Falling back to default
> theme.")
>     use_ovs_theme = False
> 
> then
> 
> if use_ovs_theme:
>     html_theme = 'ovs'
> else:
>     html_theme = 'default'

This code only runs at all if sphinx is installed, since it's
sphinx-build that runs it.  The conditional is whether the OVS sphinx
theme is installed.

My question is, what version of Sphinx (not OVS, not the OVS sphinx
theme) introduced a theme named "classic"?  If it is newer than the
oldest version of Sphinx that OVS requires, then this patch will break
things and we will need to make a choice:

        1. Refine the patch to use "default" if "classic" is not
           available.

        2. Live with the warning.

        3. Increase OVS's minimum required Sphinx version.

Thanks,

Ben.
Stephen Finucane April 18, 2017, 10:16 a.m. | #6
On Mon, 2017-04-17 at 10:21 -0700, Ben Pfaff wrote:
> On Mon, Apr 17, 2017 at 11:47:30AM -0500, Matthew Thode wrote:
> > On 04/17/2017 11:42 AM, Ben Pfaff wrote:
> > > On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
> > > > On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> > > > > On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via
> > > > > dev wrote:
> > > > > > Fixes the following warning.
> > > > > > 
> > > > > > WARNING: 'default' html theme has been renamed to
> > > > > > 'classic'. Please change your
> > > > > > html_theme setting either to the new 'alabaster' default
> > > > > > theme, or to 'classic'
> > > > > > to keep using the old default.
> > > > > > 
> > > > > > As reported by https://bugs.gentoo.org/show_bug.cgi?id=6145
> > > > > > 20
> > > > > > 
> > > > > > Signed-off-by: Matthew Thode <mthode@mthode.org>
> > > > > 
> > > > > Thanks.  Do you know whether this is going to break the docs
> > > > > build for
> > > > > people with older sphinx?  That is, was "classic" introduced
> > > > > in sphinx
> > > > > sometime after 1.1 (since that's the current minimum version
> > > > > for OVS)?
> > > > > 
> > > > 
> > > > I'm not sure, the oldest version we have is 1.11.0, and the
> > > > oldest
> > > > stable version we support is 2.5.0.  This is the first I've
> > > > seen this
> > > > bug reported though.
> > > 
> > > I guess that you are talking about OVS versions, but I'm asking
> > > about
> > > Sphinx versions.  Does that make any difference?  I don't know
> > > Sphinx
> > > well at all.
> > > 
> > 
> > I was talking about OVS versions.  This code change only changes
> > anything if sphinx is not installed.
> > 
> > try:
> >     import ovs_sphinx_theme
> >     use_ovs_theme = True
> > except ImportError:
> >     print("Cannot find 'ovs_sphinx' package. Falling back to
> > default
> > theme.")
> >     use_ovs_theme = False
> > 
> > then
> > 
> > if use_ovs_theme:
> >     html_theme = 'ovs'
> > else:
> >     html_theme = 'default'
> 
> This code only runs at all if sphinx is installed, since it's
> sphinx-build that runs it.  The conditional is whether the OVS sphinx
> theme is installed.
> 
> My question is, what version of Sphinx (not OVS, not the OVS sphinx
> theme) introduced a theme named "classic"?  If it is newer than the
> oldest version of Sphinx that OVS requires, then this patch will
> break
> things and we will need to make a choice:
> 
>         1. Refine the patch to use "default" if "classic" is not
>            available.
> 
>         2. Live with the warning.
> 
>         3. Increase OVS's minimum required Sphinx version.

It would appear this was a feature introduced in Sphinx 1.3.0 [1][2],
but which was reverted in Sphinx 1.3.2 [3][4]. We should handle this
but if we simply rename 'default' to 'classic' then we will break
support for Sphinx 1.1 and 1.2 users.

My suggestion would be to simply remove the 'else' clause. This will
cause Sphinx to use it's own default (alabaster in recent releases,
default/classic before that) when the 'ovs_sphinx_theme' package is not
available. I didn't do this before because the 'alabaster' theme is a
little too sparse for my liking but if it fixes issues for some folks
then I'm sure I can live with it :) I'll submit a patch shortly that
will do just this.

Stephen

PS: If you're using a package then you might want to talk to the
maintainers of said package: 1.3.2 was released over 2 years ago and
should really be in use by now.

[1] https://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/theming.py#L10
4-L108
[2] https://github.com/sphinx-doc/sphinx/commit/68021b0b
[3] https://github.com/sphinx-doc/sphinx/blob/1.3.2/sphinx/theming.py#L
104-L110
[3] https://github.com/sphinx-doc/sphinx/commit/034c4e94

> Thanks,
> 
> Ben.
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
Ben Pfaff April 21, 2017, 9:36 p.m. | #7
On Tue, Apr 18, 2017 at 11:16:42AM +0100, Stephen Finucane wrote:
> On Mon, 2017-04-17 at 10:21 -0700, Ben Pfaff wrote:
> > On Mon, Apr 17, 2017 at 11:47:30AM -0500, Matthew Thode wrote:
> > > On 04/17/2017 11:42 AM, Ben Pfaff wrote:
> > > > On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
> > > > > On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> > > > > > On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via
> > > > > > dev wrote:
> > > > > > > Fixes the following warning.
> > > > > > > 
> > > > > > > WARNING: 'default' html theme has been renamed to
> > > > > > > 'classic'. Please change your
> > > > > > > html_theme setting either to the new 'alabaster' default
> > > > > > > theme, or to 'classic'
> > > > > > > to keep using the old default.
> > > > > > > 
> > > > > > > As reported by https://bugs.gentoo.org/show_bug.cgi?id=6145
> > > > > > > 20
> > > > > > > 
> > > > > > > Signed-off-by: Matthew Thode <mthode@mthode.org>
> > > > > > 
> > > > > > Thanks.  Do you know whether this is going to break the docs
> > > > > > build for
> > > > > > people with older sphinx?  That is, was "classic" introduced
> > > > > > in sphinx
> > > > > > sometime after 1.1 (since that's the current minimum version
> > > > > > for OVS)?
> > > > > > 
> > > > > 
> > > > > I'm not sure, the oldest version we have is 1.11.0, and the
> > > > > oldest
> > > > > stable version we support is 2.5.0.  This is the first I've
> > > > > seen this
> > > > > bug reported though.
> > > > 
> > > > I guess that you are talking about OVS versions, but I'm asking
> > > > about
> > > > Sphinx versions.  Does that make any difference?  I don't know
> > > > Sphinx
> > > > well at all.
> > > > 
> > > 
> > > I was talking about OVS versions.  This code change only changes
> > > anything if sphinx is not installed.
> > > 
> > > try:
> > >     import ovs_sphinx_theme
> > >     use_ovs_theme = True
> > > except ImportError:
> > >     print("Cannot find 'ovs_sphinx' package. Falling back to
> > > default
> > > theme.")
> > >     use_ovs_theme = False
> > > 
> > > then
> > > 
> > > if use_ovs_theme:
> > >     html_theme = 'ovs'
> > > else:
> > >     html_theme = 'default'
> > 
> > This code only runs at all if sphinx is installed, since it's
> > sphinx-build that runs it.  The conditional is whether the OVS sphinx
> > theme is installed.
> > 
> > My question is, what version of Sphinx (not OVS, not the OVS sphinx
> > theme) introduced a theme named "classic"?  If it is newer than the
> > oldest version of Sphinx that OVS requires, then this patch will
> > break
> > things and we will need to make a choice:
> > 
> >         1. Refine the patch to use "default" if "classic" is not
> >            available.
> > 
> >         2. Live with the warning.
> > 
> >         3. Increase OVS's minimum required Sphinx version.
> 
> It would appear this was a feature introduced in Sphinx 1.3.0 [1][2],
> but which was reverted in Sphinx 1.3.2 [3][4]. We should handle this
> but if we simply rename 'default' to 'classic' then we will break
> support for Sphinx 1.1 and 1.2 users.
> 
> My suggestion would be to simply remove the 'else' clause. This will
> cause Sphinx to use it's own default (alabaster in recent releases,
> default/classic before that) when the 'ovs_sphinx_theme' package is not
> available. I didn't do this before because the 'alabaster' theme is a
> little too sparse for my liking but if it fixes issues for some folks
> then I'm sure I can live with it :) I'll submit a patch shortly that
> will do just this.

This is great.  Thank you.

> PS: If you're using a package then you might want to talk to the
> maintainers of said package: 1.3.2 was released over 2 years ago and
> should really be in use by now.

I personally seem to be using Sphinx 1.4.9, but I'm trying to preserve
compatibility with the versions that we seem to claim to support.

Patch

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 49514ec..8dffcf5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -146,7 +146,7 @@  linkcheck_anchors = False
 if use_ovs_theme:
     html_theme = 'ovs'
 else:
-    html_theme = 'default'
+    html_theme = 'classic'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the