Convert PyNEST example sources to notebooks and provide function to run notebooks on EBRAINS

[jessica-mitchell]

This PR makes Jupyter notebooks the source filetype of PyNEST examples rather than Python files. It also provides a link to running a notebook instance on EBRAINS services as well as a download for Python.

How to run Jupyter notebooks:

We have the ability to run notebooks via https://jupyterhub.github.io/nbgitpuller/link.html (thanks to @terhorstd for sharing). We provide a Jupyter Hub URL, a git repository, and the notebook we want to open, and this application generates a link that will open that file in a running Jupyter lab instance. We think this is a very good use case for highlighting EBRAINS services, since anyone with an account has access to the Jupyter lab, and NEST is installed in the most recent kernels on EBRAINS (22.07). But this link does not limit us to only using EBRAINS so we have the potential for many other use cases in the future.

Because this nbgitpuller requires a notebook to be found in the repository, we decided that the PyNEST examples should thus be converted to notebooks.

Here is what has changed

• The extension Sphinx gallery was used til now to convert the Python files into notebooks, restructured text and python files. The notebooks generated from this extension were copied into pynest/examples/notebooks to be used as source files.
• Sphinx gallery extension is removed, and links to auto_examples also removed
• A small script added to conf.py goes through each notebook and creates a button link for running the notebook on EBRAINS and downloading the Python file
  • The Python file is created via nbconvert Python exporter
  • The button links are appended to each notebook using nbformat

This PR is not complete (setting as draft) the following tasks/problems need to be resolved:

• For local build, a symlink was created between pynest/examples/notebooks and the doc/html/pynest-examples/ (documentation generator only looks at doc folder so files need to be found in the htmldoc folder)
  • [x] Button Links are appended everytime make html is run (local build) (because we have symlink so original files are updated with the button link). Maybe add a way to skip if already exists.

• [ ] For Read the docs, a direct copy from pynest/examples to doc/htmldoc/pynest-examples/ is used rather than symlink. This means the behavior between local and rtd build will differ (as it does already to some extent). The more differences we have between the two builds, the harder it makes maintaining the documentation. Not sure what a good solution is to this.

• [ ] A review of the output in HTML and in a Jupyterlab for each notebook needs to be done to make sure it works and everything renders properly

• [ ] Python files also need to be reviewed (have a bit of cleanup done)

• [ ] Prettify the Python button

• [ ] Add Jupyter logo to try it on EBRAINS?

• [x] A few pynest/examples have not been converted (those in subdirectories, like sudoku)

• [ ] A few notebooks do not work (fail to execute successfully), need to fix these; they were not copied into the notebooks folder

• [ ] python examples are still there and need to be removed (waiting that all fixes are done)

• [x] Need to update the links in examples/index.rst

• [ ] Can also add a download notebook button too for users who dont have EBRAINS access

• [ ] Might need to explain somewhere a few steps in the EBRAINS side (choosing server location, correct kernel)

• [ ] Need to update the link to run in either master or stable (if possible). Currently using jessica-mitchell/nest-simulator and ebrains-button branch. (also note that the link puller seemingly can only link to the default branch on the repo)

• [ ] Need to update styleguide and example template for notebooks

• [ ] The Python code that was added to conf.py needs a good do-over by a Python expert!

@terhorstd @steffengraber Please read above, and add any other comments, suggestions. @diesmann FYI (work in progress, see output below)

See https://nest-test.readthedocs.io/en/ebrains-button/examples/index.html for example Click on link to an example and scroll to bottom to see buttons and try out.