Remove or move examples to documentation

[kosack]

fixes #931
fixes #657

• improved the CameraDisplay and ArrayDisplay example notebooks in the docs
• moved some code from the old examples into notebook
• removed all old script examples

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[kosack]

Note that this is only a first step to cleaning up the example and tutorial notebooks. The intention here is not to fix all of them, but just to remove the script example and make sure anything interesting in them was moved to the notebooks. There will have to be a more complete overhaul of the documentation notebooks at a future point, as they are missing a large amount of information and contain some outdated practices.

[maxnoe]

Some errors in the docs build, seems like a spurious space?

 /home/runner/work/ctapipe/ctapipe/docs/ctapipe_api/coordinates/index.rst:41: WARNING: [Errno 2] No such file or directory: '/home/runner/work/ctapipe/ctapipe/docs/../ctapipe_api/coordinates/plot_camera_frames.py'
/home/runner/work/ctapipe/ctapipe/docs/ctapipe_api/visualization/index.rst:26: WARNING: [Errno 2] No such file or directory: '/home/runner/work/ctapipe/ctapipe/docs/../examples/plot_hillas_parameters.py'
/home/runner/work/ctapipe/ctapipe/docs/examples/index.rst:18: WARNING: toctree contains reference to nonexisting document 'examples/ camera_display'
/home/runner/work/ctapipe/ctapipe/docs/examples/index.rst:18: WARNING: toctree contains reference to nonexisting document 'examples/ array_display'
/home/runner/work/ctapipe/ctapipe/docs/examples/index.rst:18: WARNING: toctree contains reference to nonexisting document 'examples/ shower_core'
looking for now-outdated files... none found
pickling environment... done
/home/runner/work/ctapipe/ctapipe/docs/examples/array_display.ipynb: WARNING: document isn't included in any toctree
/home/runner/work/ctapipe/ctapipe/docs/examples/camera_display.ipynb: WARNING: document isn't included in any toctree
/home/runner/work/ctapipe/ctapipe/docs/examples/shower_core.ipynb: WARNING: document isn't included in any toctree
checking consistency... done
preparing documents... done
writing output... [ 14%] api/ctapipe.atmosphere.AtmosphereDensityProfile .. api/ctapipe.coordinates.EastingNorthingFrame
writing output... [ 28%] api/ctapipe.coordinates.EngineeringCameraFrame .. api/ctapipe.core.traits.Unicode
writing output... [ 42%] api/ctapipe.core.traits.classes_with_traits .. api/ctapipe.image.largest_island
writing output... [ 57%] api/ctapipe.image.leakage_parameters .. api/ctapipe.instrument.camera.geometry.UnknownPixelShapeWarning
writing output... [ 71%] api/ctapipe.instrument.camera.readout.CameraReadout .. api/ctapipe.reco.reconstructor.Reconstructor
../CHANGES.rst:24: WARNING: py:obj reference target not found: examples/

[maxnoe]

Looks good, my only comment would be if we really need both the ArrayDisplay noteboko and the ShowerCore notebook, both deal with the ArrayDisplay, right? Maybe join them?

[kosack]

Looks good, my only comment would be if we really need both the ArrayDisplay noteboko and the ShowerCore notebook, both deal with the ArrayDisplay, right? Maybe join them?

Done

[maxnoe]

I think it makes sense to pin nbsphinx to 0.8 as part of this PR to have the notebooks render correctly with our old sphinx version.

nbsphinx~=0.8.12 in setup.cfg and nbsphinx >=0.8.12,<0.9 in environment.yaml`

[maxnoe]

I added the pin. @Tobychev Could you approve again?