Documentation build problems

The documentation does not build out of the box for me.

With a fresh checkout and virtualenv setup, I get this error:

$ make html

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/sphinx/config.py", line 319, in eval_config_file
    execfile_(filename, namespace)
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 81, in execfile_
    exec(code, _globals)
  File "/private/tmp/librosa/docs/conf.py", line 60, in <module>
    raise RuntimeError("You need a recent enough version of matplotlib")
RuntimeError: You need a recent enough version of matplotlib

Turns out this actually a suppressed version of this traceback:

# in conf.py
>>> from matplotlib.sphinxext import plot_directive

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/matplotlib/sphinxext/plot_directive.py", line 152, in <module>
    import matplotlib.pyplot as plt
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/matplotlib/pyplot.py", line 2282, in <module>
    switch_backend(rcParams["backend"])
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/matplotlib/pyplot.py", line 221, in switch_backend
    backend_mod = importlib.import_module(backend_name)
  File "/Users/j/.asdf/installs/python/3.8.2/lib/python3.8/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/matplotlib/backends/backend_tkagg.py", line 1, in <module>
    from . import _backend_tk
  File "/private/tmp/librosa/docs/venv/lib/python3.8/site-packages/matplotlib/backends/_backend_tk.py", line 6, in <module>
    import tkinter as tk
  File "/Users/j/.asdf/installs/python/3.8.2/lib/python3.8/tkinter/__init__.py", line 36, in <module>
    import _tkinter # If this fails your Python may not be configured for Tk
ModuleNotFoundError: No module named '_tkinter'

Ok, somehow matplotlib tries to load a Tk based renderer (?!). If I manually change the matplotlib code to not use the Tk backend, now I get this error:

$ make html
...
generating gallery...

Configuration error:
The 'backreferences_dir' parameter must be of type str, pathlib.Path or None, found type <class 'bool'>
make: *** [html] Error 2

Ok, seems like I have to change this param from False to None. Now I get this error:

$ make html
...
generating gallery for auto_examples... [ 11%] plot_presets.py
Extension error:
Could not find internal sphinx-gallery thumbnail file:
/private/tmp/librosa/docs/auto_examples/images/thumb/sphx_glr_plot_presets_thumb.png
make: *** [html] Error 2

This is where I’m stuck.

Software versions: Python 3.8.2

$ pip freeze
alabaster==0.7.12
appdirs==1.4.4
attrs==19.3.0
audioread==2.1.8
Babel==2.8.0
black==19.10b0
certifi==2020.4.5.1
cffi==1.14.0
chardet==3.0.4
click==7.1.2
colorclass==2.2.0
cycler==0.10.0
decorator==4.4.2
docutils==0.16
idna==2.9
imagesize==1.2.0
Jinja2==2.11.2
joblib==0.15.1
kiwisolver==1.2.0
-e git+https://github.com/librosa/librosa@2c730101897bd3f52e149ac95d56820002f5e589#egg=librosa
llvmlite==0.32.1
MarkupSafe==1.1.1
matplotlib==3.2.1
numba==0.49.1
numpy==1.18.5
numpydoc==1.0.0
packaging==20.4
pathspec==0.8.0
Pillow==7.1.2
presets==0.1.3
pycparser==2.20
Pygments==2.6.1
pyparsing==2.4.7
python-dateutil==2.8.1
pytz==2020.1
regex==2020.5.14
requests==2.23.0
resampy==0.2.2
scikit-learn==0.23.1
scipy==1.4.1
six==1.15.0
snowballstemmer==2.0.0
SoundFile==0.10.3.post1
Sphinx==3.0.4
sphinx-gallery==0.7.0
sphinx-rtd-theme==0.4.3
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
sphinxcontrib-versioning==2.2.1
sphinxcontrib-websupport==1.2.2
threadpoolctl==2.1.0
toml==0.10.1
typed-ast==1.4.1
urllib3==1.25.9

[jonashaag]

Building from gh-pages was very easy, thanks for the pointer!

[bmcfee]

Given that a doc build takes several hours to cover all historical releases

FWIW, I think a documentation that takes, say, <30 minutes per commit to build is absolutely reasonable for CI.

Agreed, but I wasn’t exaggerating. A full doc build takes around 3-4 hours on my machine. Obviously this it because of how sphinx-versioning serializes builds, which I think is inevitable due to its dependence on git branches and tags. Maybe there’s a better solution, but I haven’t found one yet.

We ran a poll a few months back, and found that people really do value having historical docs, so I don’t want to lose that.