Convert thematic tutorial to Jupyter notebook/broken tutorial links

[Anne Schilling]

Hi All,

I was wondering whether there is an easy way to convert an existing thematic tutorial (for example https://doc.sagemath.org/html/en/thematic_tutorials/tutorial-objects-and-classes.html#tutorial-objects-and-classes ) to a Jupyter notebook?

Also, I noticed that several links on the site

https://doc.sagemath.org/html/en/thematic_tutorials/index.html

are broken. For example https://doc.sagemath.org/html/en/prep/Symbolics-and-Basic-Plotting.html does not seem to exist.

Best wishes,

Anne

[Dima Pasechnik]

Hi Anne,

On Thu, Jan 8, 2026 at 3:15 PM Anne Schilling <anne1.s...@gmail.com> wrote:

> I was wondering whether there is an easy way to convert an existing thematic tutorial (for example https://doc.sagemath.org/html/en/thematic_tutorials/tutorial-objects-and-classes.html#tutorial-objects-and-classes ) to a Jupyter notebook?

the source is an .rst file, thus two approaches outlined in
https://stackoverflow.com/questions/76151653/convert-restructured-text-to-jupyter-notebook
ought to work

HTH
Dima

>
> Also, I noticed that several links on the site
> https://doc.sagemath.org/html/en/thematic_tutorials/index.html
> are broken. For example https://doc.sagemath.org/html/en/prep/Symbolics-and-Basic-Plotting.html does not seem to exist.
>
> Best wishes,
>
> Anne
>

> --
> You received this message because you are subscribed to the Google Groups "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/sage-devel/c11703c3-0832-4374-93c4-da5b99563650n%40googlegroups.com.

[Vishwas Bajaj]

Hi Anne,

For converting existing thematic tutorials to Jupyter notebooks, there isn’t a fully automatic one-click workflow at the moment, but there are a couple of practical options:

- The thematic tutorials are written in reStructuredText and built with Sphinx. One approach is to extract the executable Sage code blocks and convert them to notebooks using tools like "jupytext" (RST ↔ notebook) or "sphinx-nbconvert", with some manual cleanup for narrative text and directives.

- Another option is to rebuild the tutorial content directly as a ".sagews" or ".ipynb" by copying code blocks and adapting the exposition incrementally; this is how some Sage tutorial notebooks have been created in the past.

Regarding the broken links: you’re right — some of the URLs under "thematic_tutorials/" appear to be outdated. In particular, paths like "/prep/Symbolics-and-Basic-Plotting.html" no longer exist in the current documentation tree. This is likely due to documentation reorganization over time without updating the index page.

It would probably be worth opening a Trac issue (or GitHub issue, depending on the current workflow) to:

- audit the thematic tutorial index,

- fix or redirect broken links, and

- possibly clarify which tutorials are still actively maintained.

If there’s interest, converting selected thematic tutorials into maintained Jupyter notebooks could also be a nice documentation improvement project.

Best regards,

Vishwas

--

[Sébastien Labbé]

Years ago, I wrote the `sage -rst2sws` script and the first version of `sage -rst2ipynb` in sage with the help of Thierry Monteil. But this was bringing a lot of dependencies and packages to be installed (pandoc, etc.) Also, at some point it got broken and I thought it still was broken today. But, I just checked and it seems to work now! Here is what I did:

Note that I am using an old version:

$ sage -v
SageMath version 10.6.beta7, Release Date: 2025-02-21

$ sage -rst2ipynb -h
/home/slabbe/GitBox/sage/src/bin/sage: ligne 854: rst2ipynb : commande introuvable
rst2ipynb is not installed, please run "sage -i rst2ipynb"

$ sage -pip install rst2ipynb
Collecting rst2ipynb
  Downloading rst2ipynb-0.2.3-py3-none-any.whl.metadata (2.5 kB)
Collecting notedown (from rst2ipynb)
[...]

Installing collected packages: pandoc-attributes, notedown, rst2ipynb
Successfully installed notedown-1.5.1 pandoc-attributes-0.1.7 rst2ipynb-0.2.3

$ sage -rst2ipynb -h
usage: rst2ipynb [-h] [-o OUTPUT] [-k KERNEL] [-v] [-d] [input] [output]
Convert a reStructuredText (.rst) file to a Jupyter notebook (.ipynb)
positional arguments:
  input                 input file (default: read from standard input)
  output                output file (default: write to standard output)
options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        output file
  -k KERNEL, --kernel KERNEL
                        sets the Jupyter kernel in the notebook
  -v, --verbose         be verbose
  -d, --debug           write debug information and keep temporary .md file

$ vim file.rst
$ cat file.rst
title
=====

Testing a cell::

    sage: 4 + 5
    9

Testing latex : $\alpha$

Testing latex differently: `\alpha`

$ sage -rst2ipynb yo.rst yo.ipynb
$ sage -n

It works:

[Sébastien Labbé]

And then:

$ cd src/doc/en/thematic_tutorials/
$ sage -rst2ipynb tutorial-objects-and-classes.rst tutorial-objects-and-classes.ipynb
$ sage -n

gives:

[kcrisman]

That's awesome that those tools still work!  Great job - it would be neat if we could have that tested as part of our framework, but since I don't know how the modern CI stuff works I can't make specific recommendations.  (For that matter a potential ipynb2rst could be useful if we will continue to have our documentation in rst format.)