DOC: Adding notebook conversion guide

doc/source/dev/contributor/rendering_documentation.rst

@@ -109,6 +109,72 @@ on the cloud.
 #. Back in GitHub, at the bottom of the PR, select “Show all Checks”.
 #. Next to “Check the rendered docs here!”, select “Details”.
 
+.. _adding-notebooks:
+
+Adding or editing tutorials as Jupyter notebooks
+------------------------------------------------
+
+Under the ``doc/source/notebooks/`` folder of the SciPy tree you can find a few
+documents written in MyST-NB_ format. These files are executable, meaning that
+their content is executed when the SciPy documentation is built (locally or on
+CI) and any outputs generated by the execution are rendered in the final HTML
+files, which you can see listed in :ref:`the user guide <executable-tutorials>`.
+
+If you have a document written in Jupyter notebook format (an ``.ipynb`` file)
+and would like to submit it as part of the SciPy documentation, there are two
+options: you can convert it into a MyST Markdown file, and work with a ``.md``
+file only, or you can pair your ``.ipynb`` file with a ``.md`` file and work
+with both. Note that ``.ipynb`` files *should not* be submitted to the SciPy
+documentation.
+
+For more details, please consult the
+`MyST-NB documentation <https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html>`__.
+You can also consult the `Pairing tutorial on NumPy Tutorials <https://numpy.org/numpy-tutorials/content/pairing.html>`__
+for more information on MyST-NB, Jupytext and pairing notebooks.
+
+How to convert a ``.ipynb`` file to executable ``.md`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't need to keep the ``.ipynb`` file, and want to work with MyST
+Markdown only, follow the steps below.
+
+1. Install the jupytext_ tool, using ``pip install jupytext`` or
+   ``conda install jupytext -c conda-forge``
+2. Clear all outputs from your ``.ipynb`` file
+3. On your terminal, run ``jupytext notebook.ipynb --to myst``, where
+   ``notebook.ipynb`` should be replaced with the file you want to convert.
+
+.. _jupytext: https://jupytext.readthedocs.io
+
+Now, the resulting ``.md`` file (in MyST Markdown format) should contain a
+preamble similar to the one below, indicating that this is an executable file:
+
+::
+
+   ---
+   jupytext:
+      text_representation:
+         extension: .md
+         format_name: myst
+         format_version: 0.13
+         jupytext_version: 1.14.0
+   kernelspec:
+      display_name: Python 3 (ipykernel)
+      language: python
+      name: python3
+   ---
+
+You don't need to edit this preamble, as it is autogenerated.
+
+Opening MyST Markdown files in the Jupyter Notebook application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have the ``jupytext`` tool installed, you can open MyST Markdown ``.md``
+files in the Jupyter Notebook application and execute them, just as you would
+with a ``.ipynb`` file.
+
+.. _MyST-NB: https://myst-nb.readthedocs.io/
+
 .. _docs-guidelines:
 
 Documentation Guidelines

doc/source/tutorial/index.rst

@@ -80,10 +80,17 @@ Below, you can find the complete user guide organized by subpackages.
    While we obviously don't require you to follow these conventions in your own
    code, they are highly recommended.
 
-Below you can also find tutorials in Jupyter Notebook format.
+.. _executable-tutorials:
+
+Executable tutorials
+--------------------
+
+Below you can also find tutorials in Jupyter Notebook format. These can be
+downloaded and executed locally, and can be useful for experimentation and
+learning.
 
 .. toctree::
-   :caption: Tutorials
+   :caption: Executable tutorials
    :maxdepth: 1
 
    ../notebooks/interp_transition_guide

environment.yml

@@ -7,7 +7,7 @@ name: scipy-dev
 channels:
   - conda-forge
 dependencies:
-  - python
+  - python<=3.9
   - setuptools<60.0
   - cython
   - compilers