Bug#877109: pybtex FTBFS with Sphinx 1.6.4-1

[Ghislain Vaillant]

On 03/10/17 12:28, Dmitry Shachnev wrote:
> Control: forwarded -1 https://bitbucket.org/pybtex-devs/pybtex/pull-requests/9/
>
> Hi Ghislain,
>
> On Sat, Sep 30, 2017 at 10:40:52AM +0100, Ghislain Vaillant wrote:
>> And what the hell am I supposed to do with this?!
>>
>> Nice of you to report the issue but, without further context, I can't take
>> further actions.
>>
>> Isn't it the Dmitry's responsibility to at least communicate on the change
>> and suggest solutions for it to people impacted by RCs? If he did, please
>> point me to the announcement in case I missed it.
> Sorry for that. I was aware of 5 or 6 packages that my change could affect,
> but I did not expect that there would be more of them. Also I do not have
> the resources to rebuild all reverse dependencies for every change in Sphinx.
>
> Anyway, better late than never, so let me explain what happened there:
>
> * Sphinx has a JavaScript library (doctools.js) that it uses to perform
>    search on built HTML documents. This library is loaded from search.html
>    page, and that page should contain a DOCUMENTATION_OPTIONS JavaScript
>    object which acts like configuration for that library.
>
> * Right now, if you open /usr/share/doc/python-pybtex-doc/html/search.html
>    from your package, you will notice that search does not work. The browser
>    console will have an error like this:
>
>    searchtools.js:543:96: TypeError: suffix is undefined
>
>    It is not something that I broke; it is caused by a change in Sphinx 1.5,
>    that added one more required option (SOURCELINK_SUFFIX) which should be in
>    DOCUMENTATION_OPTIONS.

Many thanks for providing these details.

> * Good news is that you should not notice such issues yourself; dh_sphinxdoc
>    performs the sanity check for you. It had a warning about this since sphinx
>    1.5.2-2. In the latest upload I turned this warning into error, which is
>    why you get this FTBFS bug.
I see.
> * The only packages affected by this are ones that have custom templates,
>    that do not inherit from sphinx/themes/basic/layout.html. Yours has one in
>    docs/theme/layout.html.
>
> * I have just created an upstream pull request which fixes this issue. You
>    can grab the patch from there.
Thanks for working on a fix, very much appreciated.
> In future, please CC me if you want to complain about Sphinx.
>
I was complaining about the insufficiencies behind this RC, more than 
the situation with Sphinx. No offense to Adrian, but getting an RC bug 
reported without much context to work with is just plain frustrating. 
Without your intervention, this RC could have dragged for a long time.

Ghis