| Message ID | 20170417153626.7976-1-mthode@mthode.org |
|---|---|
| State | Accepted |
| Headers | show |
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)?
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.
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.
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'
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.
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
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.
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
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(-)