Bug#1084781: can't find new pydata-sphinx-theme

[Drew Parsons]

Source: pydata-sphinx-theme
Version: 0.15.4+dfsg-1
Followup-For: Bug #1084781
Control: affects 1084781 src:petsc4py
Control: block 1082552 by 1084781

petsc4py also uses pydata-sphinx-theme for docs, and FTBFS because of
this bug. The error log is

PYTHONPATH=/home/drew/projects/petsc/build/petsc4py/.pybuild/cpython3_3.12_petsc4py_real3.21/build http_proxy='127.0.0.1:9' sphinx-build -N -bhtml docs/source build/html # HTML generator
Running Sphinx v7.4.7
Not using PETSC inventory from https://petsc.org/release/objects.inv
[]
loading translations [en]... done

Exception occurred:
File "/usr/lib/python3.12/zipfile/__init__.py", line 1331, in __init__
self.fp = io.open(file, filemode)
^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '/usr/lib/python3/dist-packages/pydata_sphinx_theme/theme/pydata_sphinx_theme'


petsc4py docs are configured (conf.py) with
html_theme = 'pydata_sphinx_theme'

so sphinx is using this directive to activate
/usr/lib/python3/dist-packages/pydata_sphinx_theme/theme/pydata_sphinx_theme

But python3-pydata-sphinx-theme 0.15.4+dfsg-1 does not provide it.

If I understand correctly, theme/pydata_sphinx_theme would be defined
inside
/usr/lib/python3/dist-packages/pydata_sphinx_theme/__init__.py

Did the definition change, breaking sphinx, in v0.15?
Is pydata-sphinx-theme 0.15 only compatible with sphinx 0.8, which we
don't have yet?

[Rebecca N. Palmer]

Control: retitle -1 pydata-sphinx-theme missing templates etc
Control: reassign -1 python3-pydata-sphinx-theme

On further investigation, it looks like the
pydata_sphinx_theme/theme/pydata_sphinx_theme directory *does* exist in
the source, but isn't being installed in the package, i.e. the bug is in
pydata-sphinx-theme not pandas.

This suggests that the immediate fix is to create a
python3-pydata-sphinx-theme.install file that lists this directory.
(See the dh_install documentation.) I haven't tried that yet, but
intend to.

This directory replaces pydata_sphinx_theme/_templates, which was
installed in the previous package. I don't know why it was and this one
isn't, as nothing in the packaging obviously refers to _templates. It
*might* be because some build tool recognizes the old one but not the
new one as a standard part of Sphinx themes.

(I don't think the problem is the version of Sphinx itself, as the
upstream dependency says sphinx>=5 and we have 7.x, but it might be the
version of that build tool.)

[Rebecca N. Palmer]

The current pandas lets the documentation fail as a workaround for this,
which is also an option for anything else that uses pydata-sphinx-theme
and urgently needs to be uploaded, but is obviously not a real solution.

Adding 'stb compile' to the build *maybe* worked, but not reliably (and
I'm not sure if it's using the installed nodejs or downloading one) and
some tests still fail:
https://salsa.debian.org/rnpalmer-guest/pydata-sphinx-theme/-/commit/296002d4ee8dd4a451ac8030fd1c23b8d99cca18/pipelines?ref=fix1084781

[Rebecca N. Palmer]

Control: merge -1 1084850

Looks like this needs at least one not-currently-packaged node.js module
and possibly several:
https://salsa.debian.org/rnpalmer-guest/pydata-sphinx-theme/-/jobs/6410726

(webpack also isn't finding the node modules it does have, but that
might be easier to fix.)

[Rebecca N. Palmer]

More details now I'm in less of a hurry:

This is my 0.15 with webpack-macros.html disabled, but I still haven't
looked at how broken its output is:
https://salsa.debian.org/python-team/packages/pydata-sphinx-theme/-/merge_requests/1

I also did some work on trying to build the full version, then reverted
it because I didn't want to upload unfinished experiments. Sorry that
this caused you to waste time redoing steps (node_version and skipping
node-css-minimizer-webpack-plugin) that I'd already had working. See
below if you still want to try.

I didn't manage to get webpack to find the installed Javascript packages
(see the history of the above branch for what I tried).  Notes for any
- Some other packages successfully use webpack (
https://codesearch.debian.net/search?q=%28%5E%7C%5B+%2C%5D%29webpack+path%3Adebian%2Fcontrol&literal=0 ), so looking at them and/or using pkg-js-tools might help.  However, no other Debian package appears to use sphinx-theme-builder or nodeenv (heat-dashboard and masakari-dashboard say they build-depend on nodeenv but don't appear to actually run it).
- I suspect the error message
"/builds/rnpalmer-guest/pydata-sphinx-theme/debian/output/source_dir/src/node_modules doesn't exist or is not a directory" isn't actually accurate; it appears to come from https://sources.debian.org/src/node-enhanced-resolve/5.15.0-1/lib/ModulesInHierarchicalDirectoriesPlugin.js/?hl=75#L75, so adding some debug prints there might be a good investigation method.
node-sass (RFP #998024; that suggests that rsass or node-node-sass
*might* be an alternative), node-sass-loader, and newer versions of
libjs-popper.js and node-mini-css-extract-plugin.