Trying to build docs locally

[paw-lu]

What I'm trying to do

Build seaborn's v0.12.0 docs locally. Ultimately automate the building of seaborn's docs with every release.

Where I fail

I cannot get v0.12.0 (specifically 231f1ba) to build. I've even gone so far as to run the ci.yml GitHub action on my own file, and the same error occurs. Is 231f1ba not a good commit to try to build the docs? I see the 0.12.0 branch has progressed a bit further than that commit.

Local reproducible example:

% gh repo clone mwaskom/seaborn

% cd seaborn

% git checkout 231f1ba61c  # This hash was associated with release of 0.12.0

% python -m pip install --upgrade pip

% python -m pip install '.[stats]' -r ci/utils.txt

% python -m pip install -r doc/requirements.txt

% NB_KERNEL=python make -C doc notebooks
../tools/nb_to_doc.py aesthetics.ipynb ../tutorial
../tools/nb_to_doc.py axis_grids.ipynb ../tutorial
Traceback (most recent call last):
  File "/Users/pawlu/Documents/personal/seaborn/doc/_tutorial/../tools/nb_to_doc.py", line 126, in <module>
    ep.preprocess(nb, {"metadata": {"path": basedir}})
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbconvert/preprocessors/execute.py", line 91, in preprocess
    self.preprocess_cell(cell, resources, index)
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbconvert/preprocessors/execute.py", line 112, in preprocess_cell
    cell = self.execute_cell(cell, index, store_history=True)
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbclient/util.py", line 85, in wrapped
    return just_run(coro(*args, **kwargs))
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbclient/util.py", line 60, in just_run
    return loop.run_until_complete(coro)
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nest_asyncio.py", line 90, in run_until_complete
    return f.result()
  File "/usr/local/Cellar/[email protected]/3.9.13_3/Frameworks/Python.framework/Versions/3.9/lib/python3.9/asyncio/futures.py", line 201, in result
    raise self._exception
  File "/usr/local/Cellar/[email protected]/3.9.13_3/Frameworks/Python.framework/Versions/3.9/lib/python3.9/asyncio/tasks.py", line 256, in __step
    result = coro.send(None)
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbclient/client.py", line 1019, in async_execute_cell
    await self._check_raise_for_error(cell, cell_index, exec_reply)
  File "/Users/pawlu/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/nbclient/client.py", line 913, in _check_raise_for_error
    raise CellExecutionError.from_cell_and_msg(cell, exec_reply_content)
nbclient.exceptions.CellExecutionError: An error occurred while executing the following cell:
------------------
g = sns.PairGrid(iris)
g.map_diag(sns.histplot)
g.map_offdiag(sns.scatterplot)
------------------

StopIteration                             Traceback (most recent call last)
Cell In [19], line 2
      1 g = sns.PairGrid(iris)
----> 2 g.map_diag(sns.histplot)
      3 g.map_offdiag(sns.scatterplot)

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/seaborn/axisgrid.py:1507, in PairGrid.map_diag(self, func, **kwargs)
   1505     plot_kwargs.setdefault("hue_order", self._hue_order)
   1506     plot_kwargs.setdefault("palette", self._orig_palette)
-> 1507     func(x=vector, **plot_kwargs)
   1508     ax.legend_ = None
   1510 self._add_axis_labels()

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/seaborn/distributions.py:1418, in histplot(data, x, y, hue, weights, stat, bins, binwidth, binrange, discrete, cumulative, common_bins, common_norm, multiple, element, fill, shrink, kde, kde_kws, line_kws, thresh, pthresh, pmax, cbar, cbar_ax, cbar_kws, palette, hue_order, hue_norm, color, log_scale, legend, ax, **kwargs)
   1416     else:
   1417         method = ax.plot
-> 1418     color = _default_color(method, hue, color, kwargs)
   1420 if not p.has_xy_data:
   1421     return ax

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/seaborn/utils.py:139, in _default_color(method, hue, color, kws)
    134     scout.remove()
    136 elif method.__name__ == "bar":
    137
    138     # bar() needs masked, not empty data, to generate a patch
--> 139     scout, = method([np.nan], [np.nan], **kws)
    140     color = to_rgb(scout.get_facecolor())
    141     scout.remove()

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/matplotlib/__init__.py:1423, in _preprocess_data.<locals>.inner(ax, data, *args, **kwargs)
   1420 @functools.wraps(func)
   1421 def inner(ax, *args, data=None, **kwargs):
   1422     if data is None:
-> 1423         return func(ax, *map(sanitize_sequence, args), **kwargs)
   1425     bound = new_sig.bind(ax, *args, **kwargs)
   1426     auto_label = (bound.arguments.get(label_namer)
   1427                   or bound.kwargs.get(label_namer))

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/matplotlib/axes/_axes.py:2373, in Axes.bar(self, x, height, width, bottom, align, **kwargs)
   2371 x0 = x
   2372 x = np.asarray(self.convert_xunits(x))
-> 2373 width = self._convert_dx(width, x0, x, self.convert_xunits)
   2374 if xerr is not None:
   2375     xerr = self._convert_dx(xerr, x0, x, self.convert_xunits)

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/matplotlib/axes/_axes.py:2182, in Axes._convert_dx(dx, x0, xconv, convert)
   2170 try:
   2171     # attempt to add the width to x0; this works for
   2172     # datetime+timedelta, for instance
   (...)
   2179     # removes the units from unit packages like `pint` that
   2180     # wrap numpy arrays.
   2181     try:
-> 2182         x0 = cbook._safe_first_finite(x0)
   2183     except (TypeError, IndexError, KeyError):
   2184         pass

File ~/.virtualenvs/seaborn-szli/lib/python3.9/site-packages/matplotlib/cbook/__init__.py:1749, in _safe_first_finite(obj, skip_nonfinite)
   1746     raise RuntimeError("matplotlib does not "
   1747                        "support generators as input")
   1748 else:
-> 1749     return next(val for val in obj if safe_isfinite(val))

StopIteration:
StopIteration:

make[1]: *** [../tutorial/axis_grids.rst] Error 1
make: *** [tutorials] Error 2

Context

Trying to automate building some crucial python documentation to upload to Kapeli/Dash-User-Contributions in order to keep documentation up-to-date. Seaborn is the first one of these I'm doing.

[mwaskom]

I believe you've run into matplotlib/matplotlib#24127

[paw-lu]

Adding constraints (matplotlib!=3.6.1) (like I see you did to the dependencies in later commits) fixes the issue! Big thanks!

[mwaskom]

BTW not familiar with your particular usecase here but do you actually need to build the docs locally or would it suffice to grab a tarball of the site from https://github.com/seaborn/seaborn.github.io/tags?

[paw-lu]

but do you actually need to build the docs locally

No, not really. As long as the objects.inv exists—which it does in seaborn/seaborn.github.io—then I think I can use that.

I later discovered seaborn/seaborn.github.io—and will probably eventually migrate to that—but wanted to start with something more generic that can be applied to other Python libraries (few libraries have their own docs repo like seaborn does) before moving seaborn over to reading from seaborn/seaborn.github.io directly.

(again) thanks a lot for the help here!