Bug#877109: pybtex FTBFS with Sphinx 1.6.4-1

[Dmitry Shachnev]

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.

* 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.

* 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.

In future, please CC me if you want to complain about Sphinx.

--
Dmitry Shachnev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/debian-science-maintainers/attachments/20171003/3ff26d9d/attachment.sig>