link to and partially copy regression/README into the index file (#5)

Author: gabalafou

doc/source/regression/README.md

@@ -12,7 +12,7 @@ JupyterLab. For this reason, each example page in this folder includes a header
 that adds a blurb to the top of each page about how the page can be
 run or downloaded as a Jupyter notebook.
 
-There a few shortcomings to this approach of generating the code cell outputs in
+There are a few shortcomings to this approach of generating the code cell outputs in
 the documentation pages at build time rather than hand editing them into the
 document source file. One is that we can no longer compare the generated outputs
 with the expected outputs as we used to do with doctest. Another is that we

doc/source/regression/index.rst

@@ -8,8 +8,6 @@ Usage examples
 The following pages contain various useful examples illustrating how to use and
 how not to use PyWavelets.
 
-For more usage examples see the `demo`_ directory in the source package.
-
 .. toctree::
    :maxdepth: 1
 
@@ -21,4 +19,19 @@ For more usage examples see the `demo`_ directory in the source package.
    wp2d
    gotchas
 
+The examples in this section are written in the `MyST markdown notebook format`_. This allows
+each .md file to function simultaneously as documentation that can be fed into
+Sphinx and as a source file that can be converted to the Jupyter notebook format
+(.ipynb), which can then be opened in notebook applications such as JupyterLab.
+For this reason, each example page in this folder includes a header template
+that adds a blurb to the top of each page about how the page can be run or
+downloaded as a Jupyter notebook. This is explained in greater detail in the
+`regression folder README`_.
+
+For more usage examples see the `demo`_ directory in the source package.
+
+
 .. include:: ../common_refs.rst
+
+.. _MyST markdown notebook format: https://myst-nb.readthedocs.io/en/v0.13.2/use/markdown.html
+.. _regression folder readme: https://github.com/PyWavelets/pywt/blob/main/doc/source/regression/README.md