search

LSSTDESC / firecrown

DESC Cosmology Likelihood Framework
BSD 3-Clause "New" or "Revised" License
29 stars 7 forks source link

Sphinx latex error #384

Closed vitenti closed 6 months ago

vitenti commented 7 months ago

Documentation (including 1.7.0) is not being built due to a latex issue on readthedocs server (very cryptic back trace). Reproduced on linux (my laptop) but @mattkwiecien managed to run on macos.

# Traceback:
Traceback (most recent call last):
  File "/usr/lib/python3.11/site-packages/sphinx/cmd/build.py", line 298, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.11/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/usr/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 363, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.11/site-packages/sphinx/builders/latex/__init__.py", line 318, in write
    docwriter.write(doctree, destination)
  File "/usr/lib/python3.11/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/lib/python3.11/site-packages/sphinx/writers/latex.py", line 88, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  [Previous line repeated 22 more times]
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/lib/python3.11/site-packages/sphinx/util/docutils.py", line 602, in dispatch_departure
    super().dispatch_departure(node)
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 2019, in dispatch_departure
    return method(node)
           ^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/docutils/nodes.py", line 2041, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.latex.LaTeXTranslator'> departing unknown node type: details_summary
mattkwiecien commented 6 months ago

I did some googling, couldn't find anything as to why this was happening.

I then traced back in our build history on readthedocs and found the first incidence of this build failure occurring: https://readthedocs.org/projects/firecrown/builds/22820174/

I compared the full log of this build to the build immediately prior which was succeeding: https://readthedocs.org/projects/firecrown/builds/22669363/

It appears that between these builds, the sphinx version that runs on the build server switched from v5.3.0 to v7.2.6.

When I run 

python -m sphinx -T -E -b readthedocssinglehtmllocalmedia -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/htmlzip

locally using sphinx v7.2.6 I get the failure

When I downgraded to sphinx v5.3.0 the same command builds the pdfs.

From this there must be two possibilities:

  1. The sphinx upgrade added a bug that is now causing our build to fail (unlikely)
  2. We had invalid docstrings / autosummaries generated that were failing silently and the old version of sphinx would continue, while the new version of sphinx exits.
mattkwiecien commented 6 months ago

I've narrowed down the version which causes the above exception to be raised. v7.1.2 works, v7.2.0 does not. https://www.sphinx-doc.org/en/master/changes.html

mattkwiecien commented 6 months ago

For now we decided to fix sphinx to version 7.1.2 because the possible fix isn't clear and possible fixes may require significant changes.