Bug#866166: sagemath: FTBFS with Sphinx 1.5: AttributeError: 'BuildEnvironment' object has no attribute 'citations'

[Ximin Luo]

Dmitry Shachnev:
> Hi Ximin!
> 
> On Tue, Jul 04, 2017 at 07:35:00AM +0000, Ximin Luo wrote:
>> I fixed our other issue in git and now I'm seeing these sphinxdoc errors:
>>
>> [..]
>> make[1]: Entering directory '/home/infinity0/var/lib/sage/sagemath'
>> dh_sphinxdoc -XMathJax.js -Xtranslations.js -Xsearchtools.js
>> dh_sphinxdoc: ignoring unknown JavaScript code: debian/sagemath-doc-ca/usr/share/doc/sagemath/html/ca/intro/_static/thebe-sage.js
>> [..]
>> dh_sphinxdoc: debian/sagemath-doc-en/usr/share/doc/sagemath/html/en/reference/_sources/lie_algebras.rst.txt is missing
>> debian/rules:199: recipe for target 'override_dh_sphinxdoc' failed
>> make[1]: *** [override_dh_sphinxdoc] Error 2
>>
>> Dmitry, if we need to further patch Sphinx or Sage, I'd be happy to do that.
>> But what exactly is needed? I'm not sure if I totally understood the ticket
>> you linked:
>>
>> https://github.com/sphinx-doc/sphinx/pull/2454
>>
>> Do we just need to put the equivalent of this:
>>
>> https://github.com/mitya57/matplotlib/commit/53e6bc46d2f010f9a80e0c73dceb6166705f608f
>>
>> into Sage's layout templates?
> 
> No, the problem is not in the templates, the problem is with installation
> layout.
> 
> dh_sphinxdoc (and searchtools.js) expect to to find the source files with the
> following scheme: .../_sources/ + original filename (i.e. lie_algebras.rst) +
> sourcelink_suffix if it is different from the original extension (i.e. .txt).
> 
> Here it fails to find these files. Most probably they are installed without
> the sourcelink_suffix, i.e. .../_sources/lie_algebras.rst instead of
> .../_sources/lie_algebras.rst.txt.
> 

It looks like the .txt suffixes are there, but the problem rather is that we have multiple files with the same name installed into different nested directories:

$ find debian/tmp/usr/share/doc/ -name lie_algebras.rst*
debian/tmp/usr/share/doc/sagemath/html/en/reference/algebras/_sources/lie_algebras.rst.txt
debian/tmp/usr/share/doc/sagemath/html/en/reference/categories/_sources/sage/categories/lie_algebras.rst.txt
debian/tmp/usr/share/doc/sagemath/html/en/reference/categories/_sources/sage/categories/examples/lie_algebras.rst.txt

The file contents are all different:

$ cat debian/tmp/usr/share/doc/sagemath/html/en/reference/algebras/_sources/lie_algebras.rst.txt 
Lie Algebras
============

.. toctree::
   :maxdepth: 2

   sage/algebras/lie_algebras/abelian
   sage/algebras/lie_algebras/affine_lie_algebra
   sage/algebras/lie_algebras/classical_lie_algebra
   sage/algebras/lie_algebras/examples
   sage/algebras/lie_algebras/heisenberg
   sage/algebras/lie_algebras/lie_algebra
   sage/algebras/lie_algebras/lie_algebra_element
   sage/algebras/lie_algebras/poincare_birkhoff_witt
   sage/algebras/lie_algebras/structure_coefficients
   sage/algebras/lie_algebras/virasoro

$ cat debian/tmp/usr/share/doc/sagemath/html/en/reference/categories/_sources/sage/categories/lie_algebras.rst.txt
.. nodoctest

.. _sage.categories.lie_algebras:

Lie Algebras
============

.. This file has been autogenerated.


.. automodule:: sage.categories.lie_algebras
   :members:
   :undoc-members:
   :show-inheritance:
   

$ cat debian/tmp/usr/share/doc/sagemath/html/en/reference/categories/_sources/sage/categories/examples/lie_algebras.rst.txt
.. nodoctest

.. _sage.categories.examples.lie_algebras:

Examples of a Lie algebra
=========================

.. This file has been autogenerated.


.. automodule:: sage.categories.examples.lie_algebras
   :members:
   :undoc-members:
   :show-inheritance:

> It looks like it installs using custom code in docbuild/ext/multidocs.py, not
> by enabling the standard Sphinx’ html_copy_source configuration option.
> 
> Unfortunately I cannot test sagemath build locally because it exceeds my RAM,
> but I can suggest two ways to potentially fix it:
> 
> * Add sourcelink_suffix support to multidocs.py (the “# Setup source symbolic
>   links” block). It can be obtained from app.config.html_sourcelink_suffix.
> 
> * Or set html_sourcelink_suffix to '.rst' in conf.py. This way it should be
>   the same as original extensions, so dh_sphinxdoc will not try to append it.
> 

So I guess your second option won't work but perhaps the first option might work, we just need to fiddle with the paths?

Could you also explain why exactly dh_sphinxdoc checks for these - what functionality is broken because these paths don't exist? I don't see that anyone noticed anything on the Sage upstream ticket https://trac.sagemath.org/ticket/22252 which is already merged, but then again I know that not everybody reads the documentation and checks it for flaws...

OTOH Sage uses a very custom sphinx build so it's possible that dh_sphinxdoc itself is not doing the right thing for Sage's docs - I remember filing a patch for dh_sphinxdoc for another thing that it was searching for, which for Sage was at a different location than usual. (see #841141)

X

-- 
GPG: ed25519/56034877E1F87C35
GPG: rsa4096/1318EFAC5FBBDBCE
https://github.com/infinity0/pubkeys.git