Bug#1000136: sphinx-common: dh_sphinxdoc regression with emscripten 2.0.26~dfsg-4: DOCUMENTATION_OPTIONS does not define URL_ROOT

[Dmitry Shachnev]

Hi Jonas!

On Thu, Nov 18, 2021 at 02:06:22PM +0100, Jonas Smedegaard wrote:
> dh_sphinxdoc worked fine with emscripten 2.0.26~dfsg-4 at the time it
> was released, but since then it fails:
>
> dh_sphinxdoc: error: DOCUMENTATION_OPTIONS does not define URL_ROOT

This error is correct.

Let's look at the generated search.html. It has this fragment:

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'2.0.26 (dev)',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            LINK_SUFFIX: '.html'
        };
    </script>
      <script type="text/javascript" 
src="_static/documentation_options.js"></script>

The first DOCUMENTATION_OPTIONS is good. However, documentation_options.js
overwrites it. That JS file has:

var DOCUMENTATION_OPTIONS = {
    URL_ROOT: 
document.getElementById("documentation_options").getAttribute('data-url_root'),
    VERSION: '2.0.26 (dev)',
    ...
}

But in search.html, there is no element with id="documentation_options", so
this does not work.

If you open search.html in a browser, you will see an error like this:

Uncaught TypeError: Cannot read properties of null (reading 'getAttribute')
    at documentation_options.js:2

Now, how to fix this. Emscripten uses emscripten_sphinx_rtd_theme, which is
a modification of sphinx-rtd-theme. The parent project sphinx-rtd-theme had
some fixes for Sphinx 4 between versions 0.5.1 and 1.0.0. In particular, see
this pull request:

https://github.com/readthedocs/sphinx_rtd_theme/pull/1123

Rebasing emscripten_sphinx_rtd_theme against the latest version of
sphinx-rtd-theme should fix this issue.

--
Dmitry Shachnev

signature.asc
Description: PGP signature