add notebooks in the doc

[videlec]

Use myst-nb to have notebooks in the documentation (in markdown format)

Checklist

• [x] Added an entry in doc/news/
• [x] Added a test for this change
• [x] include @chriszhang3 notebook

[videlec]

@saraedum Do you have an idea why the manual build in CI fails with

AttributeError: module 'sage_docbuild.conf' has no attribute 'pygments_style'

?

[videlec]

I copied this snippet from sage-flatsurf in conf.py

# Imitate the look of the SageMath documentation.
html_theme = sage_docbuild.conf.html_theme
html_theme_options = sage_docbuild.conf.html_theme_options
pygments_style = sage_docbuild.conf.pygments_style
pygments_dark_style = sage_docbuild.conf.pygments_dark_style
html_css_files = sage_docbuild.conf.html_css_files

[saraedum]

@saraedum Do you have an idea why the manual build in CI fails with

AttributeError: module 'sage_docbuild.conf' has no attribute 'pygments_style'

?

I guess furo is missing here:

if PythonModule("furo").is_present():
    pygments_style = "sphinx"

[videlec]

Thanks @saraedum ! Now there is another annoying error

/home/runner/work/surface-dynamics/surface-dynamics/doc/source/examples/interval_exchanges.md: Executing notebook using local CWD [mystnb]

Exception occurred:
  File "/usr/share/miniconda3/envs/test/lib/python3.10/site-packages/nbclient/client.py", line 1005, in async_execute_cell
    raise DeadKernelError("Kernel died") from None
nbclient.exceptions.DeadKernelError: Kernel died
The full traceback has been saved in /tmp/sphinx-err-v_zmamjl.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[videlec]

Seems to be because myst_nb ignores the #optional : XXX directives that I copy/pasted...

[saraedum]

Seems to be because myst_nb ignores the #optional : XXX directives that I copy/pasted...

I don't think it matters since all the dependencies are available anyway.

[saraedum]

We get a no type named 'TStreamerInfo' in namespace 'CppyyLegacy' followed by a segfault.

[saraedum]

We get a no type named 'TStreamerInfo' in namespace 'CppyyLegacy' followed by a segfault.

It's fixed now :tada:

[saraedum]

Here's the logo I am using now:

[videlec]

Here's the logo I am using now:

Nice. Though, we can not read the iet on the picture... I will think about a way to make it visible nicely.