latest doc LaTeX build fails

[hakonanes]

Builds from the latest branch fail: https://beta.readthedocs.org/projects/orix/builds/23890511/.

It's nbsphinx that throws an AssertionError in its nbsphinx/__init__.py in a function named depart_codearea_latex:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/cmd/build.py", line 298, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(['__all__'], to_build)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 363, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/builders/latex/__init__.py", line 318, in write
    docwriter.write(doctree, destination)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/writers/latex.py", line 88, in translate
    self.document.walkabout(visitor)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  [Previous line repeated 10 more times]
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/sphinx/util/docutils.py", line 599, in dispatch_departure
    method(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/orix/conda/latest/lib/python3.11/site-packages/nbsphinx/__init__.py", line 1875, in depart_codearea_latex
    assert False
AssertionError

No clear error message.

Versions:

• Sphinx 7.2.6
• nbsphinx 0.9.3

I'll try to reproduce locally and see if I can fix this.

Should be fixed before we release v0.12.

[pc494]

Thanks @hakonanes, Carter and I had had a look at this and it seemed non-obvious :(

[CSSFrancis]

https://github.com/spatialaudio/nbsphinx/blob/53be5e632f0c9483ba65ba6690da9b137f9c1120/src/nbsphinx/__init__.py#L1871-L1875

[CSSFrancis]

My best guess is that pinning the sphinx version should help to fix this?

[hakonanes]

I'm leaning towards replacing nbsphinx with Sphinx-Gallery. People can still download the tutorials as notebooks then. What do you think?

[hakonanes]

I've reported this issue to the nbsphinx developers.

As you say @CSSFrancis, we should try to make our LaTeX build work for now (e.g. by pinning to a Sphinx/nbsphinx version combination that works). We can remove the pinnings once the LaTeX build works again with newer versions.

Unless you guys want to switch to Sphinx-Gallery altogether, of course.

[pc494]

I'm happy with a pin for now and then a patch when a fix comes in if others are?

[hakonanes]

The previous successful LaTeX build was in December with the same nbsphinx that fails.

Only reverting the Sphinx version to 6.2 or 5.3 or the nbsphinx version to 0.8 doesn't fix the LaTeX build.

I think this requires a MWE to find the cause of the error.

[CSSFrancis]

@hakonanes and @pc494 Is there anything different about the latest run and what runs on a pull it's just weird to me that the documentation build fine for the Pull requests and then doesn't for the latest

[CSSFrancis]

The only difference I can think of is related to the tags?

Edit: I didn't look very closely. The error is thrown when trying to build the pdf and succeeds when building the html, it seems like it is just an issue with the pdf build.

Do we need a pdf build? I doubt that it is used and if it causes problems it might be nice to just remove that so we can get things to work.

[hakonanes]

Yes, we should provide the docs in PDF format. But I don't think the failing LaTeX build should hold up the 0.12 release. I suggest we live with the failing docs badge as a reminder to fix this.

[CSSFrancis]

@hakonanes Sounds fair. I think that moving to sphinx gallery for everything is probably the best thing to do as that has a cleaner git history and works a bit better than Jupyter notebooks.

[hakonanes]

The feature we lose switching to SG is saving outputs in the notebook, so RTD doesn't have to run the tutorial. That is crucial for some of our tutorials. We have to reconsider those tutorials before switching. I forgot about that...

[CSSFrancis]

@hakonanes can you narrow it down a bit.

Does running nbconvert on the Jupyter notebooks throw an error not in the sphinx workflow? Can you stop some of the notebook conversions to narrow down which one is causing the issue.

Then can we figure out what bit of latex is causing issues? I haven't been able to reproduce this on my laptop.

[CSSFrancis]

Is it possible that we aren't doing a great job of installing the latex packages for converting to pdf. https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex. It seems like we should be installing the TeX Live package as I don't think that pandoc natively supports conversion to pdf (https://pandoc.org). This is just me spitballing though.

[hakonanes]

I haven't been able to reproduce this on my laptop

Are you running the command run by RTD? With python -m sphinx -T -b latex -d build/doctrees -D language=en . /some_directory, I can reproduce the error.

I'll try to create an MWE for us to test with and also to provide to nbsphinx maintainers.

Is it possible that we aren't doing a great job of installing the latex packages for converting to pdf

Perhaps. But, I don't think that's the issue here, given the LaTeX build ran fine before. pandoc is required by nbsphinx for "converting Markdown to something Sphinx can understand".

[hakonanes]

This is now temporarily fixed in #495.