tommyod / KDEpy

Kernel Density Estimation in Python
https://kdepy.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
584 stars 90 forks source link

Docs failing #156

Closed tommyod closed 1 year ago

tommyod commented 1 year ago

Docs are failing. Getting a cryptic error message on readthedocs and locally.

Here is the command:

python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs/source html/html

And the error, from the logs:

# Platform:         linux; (Linux-5.15.0-84-generic-x86_64-with-glibc2.31)
# Sphinx version:   6.2.1
# Python version:   3.9.4 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.0.3
# Pygments version: 2.15.1

# Last messages:
#   looking for now-outdated files...
#   none found
#   pickling environment...
#   done
#   checking consistency...
#   done
#   preparing documents...
#   done
#   writing output... [ 12%] API
#   writing output... [ 25%] bandwidth

# Loaded extensions:
#   sphinx.ext.mathjax (6.2.1)
#   alabaster (0.7.12)
#   sphinxcontrib.applehelp (1.0.2)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   sphinx.ext.autodoc.preserve_defaults (6.2.1)
#   sphinx.ext.autodoc.type_comment (6.2.1)
#   sphinx.ext.autodoc.typehints (6.2.1)
#   sphinx.ext.autodoc (6.2.1)
#   sphinx.ext.intersphinx (6.2.1)
#   sphinx.ext.viewcode (6.2.1)
#   sphinx.ext.napoleon (6.2.1)
#   sphinx.ext.autosummary (6.2.1)
#   sphinx.ext.extlinks (6.2.1)
#   numpydoc (1.5.0)
#   nbsphinx (0.9.2)
#   matplotlib.sphinxext.plot_directive (3.7.1)
#   IPython.sphinxext.ipython_directive (unknown version)
#   IPython.sphinxext.ipython_console_highlighting (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 378, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 586, in write
    self._write_serial(sorted(docnames))
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 596, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 666, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/writers/__init__.py", line 77, in write
    self.translate()
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/writers/html.py", line 37, in translate
    self.document.walkabout(visitor)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/nodes.py", line 178, in walkabout
    visitor.dispatch_visit(self)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/util/docutils.py", line 581, in dispatch_visit
    method(node)
  File "/home/tommy/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/writers/html5.py", line 224, in visit_reference
    assert len(node) == 1 and isinstance(node[0], nodes.image)  # NoQA: PT018
AssertionError
whitews commented 1 year ago

Figured this out. It is a compatibility issue between nbsphinx and pandoc. Recent versions of nbsphinx require pandoc >= 2.14.2. However, Ubuntu 22.04 provides pandoc 2.9.2, and that is the latest OS that ReadTheDocs provides. Pinning sphinx and nbsphinx to prior versions fixes this, and we can update them in the future when RTD provides a newer OS (probably when 24.04 LTS is released).