Documentation building fails with sphinx-gallery 0.17.0

[yvonnefroehlich]

Currently building the documentation fails with:

generating gallery for projections/table... 

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx/events.py", line 98, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx_gallery/gen_gallery.py", line 796, in generate_gallery_rst
    _replace_md5(subsection_index_path, mode="t")
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx_gallery/utils.py", line 161, in _replace_md5
    assert fname_new.endswith(".new")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx/cmd/build.py", line 332, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx/application.py", line 292, in __init__
    self._init_builder()
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx/application.py", line 366, in _init_builder
    self.events.emit('builder-inited')
  File "/home/docs/checkouts/readthedocs.org/user_builds/pygmt-dev/conda/3312/lib/python3.12/site-packages/sphinx/events.py", line 109, in emit
    raise ExtensionError(
sphinx.errors.ExtensionError: Handler <function generate_gallery_rst at 0x7fd6af85a160> for event 'builder-inited' threw an exception (exception: )

Extension error (sphinx_gallery.gen_gallery):
Handler <function generate_gallery_rst at 0x7fd6af85a160> for event 'builder-inited' threw an exception (exception: )

The issue seem to be related to the README file containing the projection table.

When removing this README file building the documentation is [partly] successfull (a3a5416). I also tested changing the file extension, including *.md (d355b54, successfull) and *.rst (9080f46, failing).

[welcome]

👋 Thanks for opening your first issue here! Please make sure you filled out the template with as much detail as possible. You might also want to take a look at our contributing guidelines and code of conduct.

[seisman]

Likely related to the new sphinx-gallery release https://github.com/sphinx-gallery/sphinx-gallery/releases/tag/v0.17.0, especially this PR sphinx-gallery/sphinx-gallery#1321

[seisman]

#3348 doesn't work, so sphinx-gallery/sphinx-gallery#1321 is not the PR to blame.

It's more likely caused by changes in sphinx-gallery/sphinx-gallery#1321. Setting nested_sections=True in doc/conf.py works, but it will cause incorrect sidebar as reported in #2042.

[yvonnefroehlich]

I am wondering if it makes sense to move the projection table to the newly created "Technical Reference"? Then we can get rid of the table folder under "projections", which only contains the README file with the projection table, which seem to be the problem. With this change, for me, building the documentation works also using Sphinx-Gallery 0.17.0.
I submitted a POC PR at #3356.

Another task would be, if possible, to convert the projection table from RST to Markdown.

[seisman]

which only contains the README file with the projection table, which seem to be the problem.

I think you're right!

Another task would be, if possible, to convert the projection table from RST to Markdown.

You probably can try to convert a few lines to Markdown and see if it works.