docutils/transforms/misc.py error

[melaniewalsh]

Describe the bug

I am trying to build my JupyterBook with the latest version of of the package (and I hadn't upgraded for quite a while), and the docutils/transforms/misc.py script is throwing an error.

Does anyone know what I can change to avoid this error? It's hard for me to identify where this error is coming from, and I wondered if others who have upgraded after a while have run into something similar.

cat /var/folders/06/y6vmvyfj0wg08vb3rszcfy080000gn/T/sphinx-err-txilrytd.log
# Platform:         darwin; (macOS-14.3-arm64-arm-64bit)
# Sphinx version:   7.2.6
# Python version:   3.9.18 (CPython)
# Docutils version: 0.20.1
# Jinja2 version:   3.1.3
# Pygments version: 2.17.2

# Last messages:
#   05-Text-Analysis/10-Topic-Modeling-CSV
#   

#   reading sources... [ 60%]
#   05-Text-Analysis/11-Topic-Modeling-Time-Series
#   

#   reading sources... [ 61%]
#   05-Text-Analysis/12-Named-Entity-Recognition
#   

# Loaded extensions:
#   sphinx.ext.mathjax (7.2.6)
#   alabaster (0.7.16)
#   sphinxcontrib.applehelp (1.0.8)
#   sphinxcontrib.devhelp (1.0.6)
#   sphinxcontrib.htmlhelp (2.0.5)
#   sphinxcontrib.serializinghtml (1.1.10)
#   sphinxcontrib.qthelp (1.0.7)
#   sphinx_togglebutton (0.3.2)
#   sphinx_copybutton (0.5.2)
#   myst_nb (1.0.0)
#   jupyter_book (1.0.0)
#   sphinx_thebe (0.3.1)
#   sphinx_comments (0.0.3)
#   sphinx_external_toc (1.0.1)
#   sphinx.ext.intersphinx (7.2.6)
#   sphinx_design (0.5.0)
#   sphinx_book_theme (unknown version)
#   notfound.extension (1.0.0)
#   sphinxext.rediraffe (unknown version)
#   sphinx_jupyterbook_latex (unknown version)
#   sphinx_multitoc_numbering (unknown version)
#   pydata_sphinx_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/jupyter_book/sphinx.py", line 167, in build_sphinx
    app.build(force_all, filenames)
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 293, in build_update
    self.build(to_build,
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 313, in build
    updated_docnames = set(self.read())
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 420, in read
    self._read_serial(docnames)
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 441, in _read_serial
    self.read_doc(docname)
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 498, in read_doc
    publisher.publish()
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/core.py", line 236, in publish
    self.apply_transforms()
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/core.py", line 216, in apply_transforms
    self.document.transformer.apply_transforms()
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/sphinx/transforms/__init__.py", line 83, in apply_transforms
    super().apply_transforms()
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/transforms/__init__.py", line 182, in apply_transforms
    transform.apply(**kwargs)
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/transforms/misc.py", line 98, in apply
    self.visit_transition(node)
  File "/Users/melwalsh/anaconda3/envs/py39/lib/python3.9/site-packages/docutils/transforms/misc.py", line 108, in visit_transition
    assert (isinstance(node.parent, nodes.document)
AssertionError

problem
This is a problem for people I can't build my book with the newest version of jupyter-book.

Reproduce the bug

You can reproduce the error if you clone my repo https://github.com/melaniewalsh/Intro-Cultural-Analytics/ and try to build the book. However, I also had to re-install a couple of custom extensions that I am using before getting to this error, so you might have to do that too if you are trying to reproduce

pip install sphinxext-rediraffe    
pip install sphinx-notfound-page

List your environment

Jupyter Book      : 1.0.0
External ToC      : 1.0.1
MyST-Parser       : 2.0.0
MyST-NB           : 1.0.0
Sphinx Book Theme : 1.1.2
Jupyter-Cache     : 1.0.0
NbClient          : 0.9.0

[melaniewalsh]

I found the issue! I had multiple Jupyter notebooks where I used a display Markdown package to output Markdown in code cells, and I believe the error was getting thrown when I was displaying a horizontal line --- in Markdown in this way. You can see an example here: https://github.com/melaniewalsh/Intro-Cultural-Analytics/blob/6ed7a6625a60ee8fa5c486fd266fe8fda29a45e3/book/05-Text-Analysis/12-Named-Entity-Recognition.ipynb?short_path=66ece77#L7554

display(Markdown('---'))

As a side note, my old HTML admonitions were also causing a lot of pages to be wonky, even though they were still building.