Error during documentation generation: Jmol failed to create file

[sedimentation-fault]

I am struggling with merging of sage 9.0 into a recently-synced Gentoo.
I am using the following USE flags:

equery uses sage
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for sci-mathematics/sage-9.0-r1:
 U I
 + + X                        : Add support for X11
 + - bliss                    : build the bindings to the bliss library 
 - - debug                    : Enable extra debug codepaths, like asserts and extra output. If you want to get
                                meaningful backtraces see
                                https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
 + - doc-html                 : build and install html documentation 
 - - doc-html-bin             : install pre-built html documentation 
 + - doc-pdf                  : build and install documentation in pdf format 
 - - doc-pdf-bin              : install pre-built pdf documentation 
 - - jmol                     : Make jmol the default 3D rendering engine. Tachyon will be used otherwise.
 - - l10n_ca                  : Catalan
 + + l10n_de                  : German
 + + l10n_en                  : English
 + + l10n_es                  : Spanish
 + + l10n_fr                  : French
 - - l10n_hu                  : Hungarian
 + + l10n_it                  : Italian
 - - l10n_ja                  : Japanese
 - - l10n_pt                  : Portuguese
 - - l10n_ru                  : Russian
 - - l10n_tr                  : Turkish
 + - latex                    : Add support for LaTeX (typesetting package)
 + + python_targets_python3_6 : Build with Python 3.6
 + + python_targets_python3_7 : Build with Python 3.7
 + - testsuite                : If activated installs tools to runs the testsuite and insure that all the files needed
                                are present.

As you can see, jmol is NOT enabled. However, during documentation generation, I got:

[plot3d   ]  from /XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/doc/en/reference/plot3d/sage/plot/plot3d/plot3d.rst:
[plot3d   ] Traceback (most recent call last):
[plot3d   ]   File "/usr/lib/python3.7/site-packages/matplotlib/sphinxext/plot_directive.py", line 524, in run_code
[plot3d   ]     six.exec_(code, ns)
[plot3d   ]   File "<string>", line 4, in <module>
[plot3d   ]   File "<string>", line 43, in sphinx_plot
[plot3d   ]   File "sage/plot/plot3d/base.pyx", line 1637, in sage.plot.plot3d.base.Graphics3d.save (/XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/cythonized/sage/plot/plot3d/base.c:21660)
[plot3d   ]     self.save_image(filename, **kwds)
[plot3d   ]   File "sage/plot/plot3d/base.pyx", line 1566, in sage.plot.plot3d.base.Graphics3d.save_image (/XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/cythonized/sage/plot/plot3d/base.c:21218)
[plot3d   ]     self._save_image_png(filename, **kwds)
[plot3d   ]   File "sage/plot/plot3d/base.pyx", line 1528, in sage.plot.plot3d.base.Graphics3d._save_image_png (/XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/cythonized/sage/plot/plot3d/base.c:20855)
[plot3d   ]     scene = self._rich_repr_jmol(**opts)
[plot3d   ]   File "sage/plot/plot3d/base.pyx", line 276, in sage.plot.plot3d.base.Graphics3d._rich_repr_jmol (/XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/cythonized/sage/plot/plot3d/base.c:7494)
[plot3d   ]     jdata.export_image(targetfile=preview_png, datafile=script,
[plot3d   ]   File "/XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/lib/sage/interfaces/jmoldata.py", line 181, in export_image
[plot3d   ]     raise RuntimeError("Jmol failed to create file %s, see %s for details"%(repr(targetfile), repr(scratchout)))
[plot3d   ] RuntimeError: Jmol failed to create file '/XXXXXX/portage/sci-mathematics/sage-9.0-r1/homedir/.sage/temp/YYYYYY/6450/dir_4gdika0r/preview.png', see '/XXXXXX/portage/sci-mathematics/sage-9.0-r1/homedir/.sage/temp/YYYYYY/6450/tmp_olq02u2a.txt' for details
[plot3d   ] /XXXXXX/portage/sci-mathematics/sage-9.0-r1/work/sage-9.0/src-python3_7/build/lib/sage/plot/plot3d/plot3d.py:docstring of sage.plot.plot3d.plot3d.plot3d:166: WARNING: Exception occurred in plotting plot3d-31

Obviously, a line

doc-html? ( sci-chemistry/sage-jmol-bin )

is missing in the ebuild's BDEPEND list, as it seems that jmol is needed during the build phase, at least when the doc-html (and doc-pdf?) USE flags are enabled...

(NOTE: tachyon 0.99_beta6-r1 IS installed, but is irrelevant here).

P.S.: Thank you for going through python hell in order to give us Sage on Gentoo!

[kiwifb]

You are right, jmol is needed to build the documentation at this stage. Upstream is working on shaking it off eventually but the best candidate, threejs, is not yet capable of building the sage documentation.

I will fix this ASAP. In any case, my recommendation is that you use the pre-built documentation if you can (doc-html-bin and doc-pdf-bin) as building the documentation is expensive and at time frustrating.

[kiwifb]

Re-open if the solution is not satisfactory.

[sedimentation-fault]

my recommendation is that you use the pre-built documentation if you can (doc-html-bin and doc-pdf-bin) as building the documentation is expensive and at time frustrating.

Been there, done that. But unfortunately, this did not work well in my current situation - but it worked well in the past. Alas, I didn't keep notes in my package.use to document why I wrote

# According to the ebuild, html and bin-html are mutually exclusive - as are pdf and bin-pdf.
# We choose the bin- versions, because they are the favourites of the ebuild...
# 01.04.20: We try it the other way out...
<sci-mathematics/sage-9.0 bin-html -html -pdf bin-pdf
# >=sci-mathematics/sage-9.0 doc-pdf-bin -doc-pdf doc-html-bin -doc-html
>=sci-mathematics/sage-9.0 -doc-pdf-bin doc-pdf doc-html -doc-html-bin

Notice the commented lines and the change of mind on 01.04.20. I do know, however, that it [sphinx 1.8.5, even with the bin docs] cost me so many headaches that I decided to ditch sphinx-1.8.5 and go for 2.0. This is probably the reason why I said to myself "if I have to choose my own sphinx version, I can generate the documentation myself too!".

Now, I know that you will say "you are on your own, because sphinx-1.8.5 is the version officially endorsed by Sage at this moment" - to which I answer: did you sync your portage lately? :-)

The problem is, according to my comments on the ebuild I am using (which is a modified copy of the sage-on-gentoo ebuild, in my attempt to correct all this mess (which is NOT your fault anyway! :-)):

#   <dev-python/sphinx-2.0.0 collides with the requirement
#   >=dev-python/sphinx-2.0 from dev-python/sphinxcontrib-qthelp,
#   and dev-python/sphinxcontrib-qthelp is required by dev-python/pplpy,
#   which is required by *this* package!

This should go into a new bug report...I will write it ASAP, so we can discuss it there and do not have to pollute this thread.

[sedimentation-fault]

...and here it is: #580. :-)