[Python-modules-team] Bug#901662: sphinx: RTD theme users FTBFS with dh_sphinxdoc: DOCUMENTATION_OPTIONS does not define URL_ROOT

[Rebecca N. Palmer]

Source: sphinx
Version: 1.7.5-1
Severity: serious
Control: tags -1 patch
Control: affects -1 src:theano src:python-jira
(These are the ones I've actually checked; I suspect most/all of the 
~100 packages that build-depend on *-sphinx-rtd-theme are affected.)

sphinx's included themes have layout.html reference a separate file 
documentation_options.js (for compatibility with strict CSS policies 
[0]).  However, sphinx-rtd-theme (and possibly other 3rd party themes - 
I haven't checked) still uses the old method of defining 
DOCUMENTATION_OPTIONS as inline JavaScript within the layout.html file 
[1].  In documentation using this theme, documentation_options.js exists 
(presumably from sphinx's default template) but isn't actually used.

In 1.7.5, sphinx started passing the parameter data-url_root from 
layout.html to documentation_options.js [2], and dh_sphinxdoc also reads 
this parameter.  This dh_sphinxdoc check assumes that if 
documentation_options.js exists it is used, and hence errors out if 
documentation_options.js expects a data-url_root parameter but 
layout.html doesn't pass one.

This causes documentation using sphinx-rtd-theme to FTBFS with
dh_sphinxdoc: DOCUMENTATION_OPTIONS does not define URL_ROOT

[0] https://github.com/sphinx-doc/sphinx/pull/4295
[1] 
https://github.com/rtfd/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html
Discussion of whether this should change: 
https://github.com/rtfd/sphinx_rtd_theme/issues/414
[2] 
https://github.com/sphinx-doc/sphinx/commit/a7c6cb018067d735a470a0687248912c6148977d#diff-d108032640b69e79b413796eace2046f

Possible (but very minimally tested) fix:

--- a/debian/dh-sphinxdoc/dh_sphinxdoc
+++ b/debian/dh-sphinxdoc/dh_sphinxdoc
@@ -252,7 +252,7 @@ sub sanity_check($$)
     grep { s/[?#].*//; $js{$_} = 1 unless m/^[a-z][a-z0-9.+-]*:/i or excludefile("$path/$_"); } $search =~ m{<script type="text/javascript" src="([^"]++)"></script>}g;
     my $documentation_options;
     my $documentation_options_fn = "$path/_static/documentation_options.js";
-    if (-f $documentation_options_fn)
+    if ($search =~ $documentation_options_fn)
     {
         open(my $fh, '<', $documentation_options_fn) or error("cannot open $documentation_options_fn");
         $documentation_options = <$fh>;