Question: What is the 'xcffib' dependency used for

[bearsh]

I don't seen any import in code. Is this dependency really needed on all platform? Installation on windows seems difficult...

[bavovanachte]

Not entirely sure, looks like it was added in https://github.com/bavovanachte/sphinx-wavedrom/commit/d6067bef6a34b853e08149e82c552e0f55aa9076.

@wallento (the author of that PR) probably knows. Maybe some missing downstream dependencies?

[bearsh]

What I see:

• sphinx-wavedrom depends (code import) on cairosvg
• cairosvg depends on cairocffi
• cairocffi provides an optional xcb dep and xcb module which requires xcffib
• the xcb module is not used used (code import) by cairosvg

[cr1901]

I also ran into issues with the xcffib dep today while building documentation for a LiteX SoC:

Generate the documentation by running `sphinx-build -M html C:/msys64/home/William/Projects/FPGA/litex/SoCs/orangecrab-feather/build/gsd_orangecrab/doc/ C:/msys64/home/William/Projects/FPGA/litex/SoCs/orangecrab-feather/build/gsd_orangecrab/doc/_build`
identifier_mem@f0003000: Found memory that's 8 x 59 (but memories aren't documented yet)
Running Sphinx v4.3.2

Exception occurred:
  File "C:/msys64/mingw64/lib/python3.9/site-packages/xcffib/__init__.py", line 38, in <module>
    lib = ffi.dlopen(soname)
OSError: cannot load library 'libxcb.dll': error 0x7e
The full traceback has been saved in C:/Users/William/AppData/Local/Temp/sphinx-err-uojq8_rl.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

I've provided the log as well:

# Sphinx version: 4.3.2
# Python version: 3.9.10 (CPython)
# Docutils version: 0.18.1 release
# Jinja2 version: 3.0.3
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinx/application.py", line 237, in __init__
    self.setup_extension(extension)
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinx/application.py", line 394, in setup_extension
    self.registry.load_extension(self, extname)
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinx/registry.py", line 429, in load_extension
    mod = import_module(extname)
  File "C:/msys64/mingw64/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 850, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinxcontrib/wavedrom.py", line 15, in <module>
    from .wavedrom_render_image import render_wavedrom_image
  File "C:/msys64/mingw64/lib/python3.9/site-packages/sphinxcontrib/wavedrom_render_image.py", line 6, in <module>
    import cairosvg
  File "C:/msys64/mingw64/lib/python3.9/site-packages/cairosvg/__init__.py", line 26, in <module>
    from . import surface  # noqa isort:skip
  File "C:/msys64/mingw64/lib/python3.9/site-packages/cairosvg/surface.py", line 9, in <module>
    import cairocffi as cairo
  File "C:/msys64/mingw64/lib/python3.9/site-packages/cairocffi/__init__.py", line 125, in <module>
    from .xcb import XCBSurface  # noqa isort:skip
  File "C:/msys64/mingw64/lib/python3.9/site-packages/cairocffi/xcb.py", line 11, in <module>
    from xcffib import visualtype_to_c_struct
  File "C:/msys64/mingw64/lib/python3.9/site-packages/xcffib/__init__.py", line 38, in <module>
    lib = ffi.dlopen(soname)
OSError: cannot load library 'libxcb.dll': error 0x7e

Seeing that I'm running Windows, libxcb.dll is unlikely to exist I imagine. So this error is expected. But it does mean I can't generate documentation for LiteX SoCs now (tbf, I'm not sure if doc generation ever worked on Windows, but it's been over a year since I touched my code and am refreshing it).

[bavovanachte]

It seems I need to take a look at some alternatives to cairosvg, as well as set up testing on windows machines. Adding "help wanted" as I have a feeling this will be hard to reproduce.

[cr1901]

FWIW, I was able to get sphinx-wavedrom to install, and the example to compile on Windows 10 with the following patch:

diff --git a/example/source/conf.py b/example/source/conf.py
index bb235e9..4566cf1 100644
--- a/example/source/conf.py
+++ b/example/source/conf.py
@@ -61,7 +61,7 @@ release = '1.0'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'

 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/setup.py b/setup.py
index 722ff18..faf9a30 100644
--- a/setup.py
+++ b/setup.py
@@ -4,8 +4,7 @@ project_url = 'https://github.com/bavovanachte/sphinx-wavedrom'

 requires = ['Sphinx>=1.8',
             'wavedrom>=1.9.0rc1',
-            'cairosvg>=2;python_version>="3.3"',
-            'xcffib;python_version>="3.3"']
+            'cairosvg>=2;python_version>="3.3"',]

 setup(
     name='sphinxcontrib-wavedrom',

Tyvm @whitequark for pointing out that xcffib is a top-level dep that's not used for e.g. HTML generation. Could PDF generation become an optional feature (disabled on Windows) as an interim solution?