From bf91fd6aca5fb4e9908479943c9b9295bd9baa9b Mon Sep 17 00:00:00 2001
From: Adam Tyson <code@adamltyson.com>
Date: Wed, 3 Jan 2024 15:11:23 +0000
Subject: [PATCH] Update brainrender notebook docs (#131)

* Update instructions for using brainrender with notebooks

* Add sphinx-copybutton
---
 docs/requirements.txt                         |  1 +
 docs/source/conf.py                           |  1 +
 .../brainrender/usage/using-notebooks.md      | 63 +++++++++++--------
 3 files changed, 39 insertions(+), 26 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2311d2a4..f44f3f37 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -8,4 +8,5 @@ sphinx-design
 sphinx-togglebutton
 sphinx-notfound-page
 sphinx-sitemap
+sphinx-copybutton
 ablog>=0.11.0rc2
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b0d643ff..90151e5a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -45,6 +45,7 @@
     "numpydoc",
     "nbsphinx",
     "notfound.extension",
+    "sphinx_copybutton"
 ]
 
 # Configure the myst parser to enable cool markdown features
diff --git a/docs/source/documentation/brainrender/usage/using-notebooks.md b/docs/source/documentation/brainrender/usage/using-notebooks.md
index 3c518e20..52a372c1 100644
--- a/docs/source/documentation/brainrender/usage/using-notebooks.md
+++ b/docs/source/documentation/brainrender/usage/using-notebooks.md
@@ -5,20 +5,31 @@
 1. you can **embed** a window with your rendered scene
 2. you can have your scene be rendered in a **pop-up** window.
 
-For an example of how to use `brainrender` with `jupyter` have a look 
-[here](https://github.com/brainglobe/brainrender/blob/master/examples/notebook_workflow.ipynb).
 
 ## Rendering your scene in a separate window
 
-If you want to have your scene be rendered in a new window, then you just need to set this option before your create your `scene`.
+If you want your scene to be rendered in a new window, then set this option before you create 
+your `Scene`.
 
 ```python
-from vedo import embedWindow
-embedWindow(None) 
+import vedo
+vedo.settings.default_backend= 'vtk'
 ```
 
-After this everything will work exactly the same as usual, and you will have access to all of `brainrender`'s features!
+After this everything will work exactly the same as usual, and you will have access to all of `brainrender`'s features.
+E.g. to visualise primary visual cortex in the Allen Adult Mouse Brain Atlas:
 
+```python
+import vedo
+vedo.settings.default_backend= 'vtk'
+
+from brainrender import Scene
+popup_scene = Scene(atlas_name='allen_mouse_50um', title='popup')
+
+popup_scene.add_brain_region('VISp')
+
+popup_scene.render()  # press 'Esc' to close
+```
 ## Embedding renderings in Jupyter notebooks
 
 :::{hint}
@@ -28,32 +39,32 @@ If you want to support all of `brainrender`'s features you should **not embed**
 Note that this is due to the backend \(`k3d`\) used to embed the renderings not because of `brainrender`.
 :::
 
-If you want to embed your scene anyway, you can do that as either a `k3d` panel or a with `itkwidgets` by setting:
+If you still need to embed your `Scene` then `brainrender` works slightly differently. E.g. to visualise the 
+tectum in the larval zebrafish atlas:
 
 ```python
-embedWindow('k3d') # or 'itkwidgets' 
-```
+# Set the backend
+import vedo
+vedo.settings.default_backend= 'k3d'
 
-If you chose `k3d` then to rendered your scene:
+# Create a brainrender scene
+from brainrender import Scene
+scene = Scene(atlas_name='mpin_zfish_1um', title='Embedded')  # note the title will not actually display
+scene.add_brain_region('tectum')
 
-```python
-from vedo import show
+# Make sure it gets embedded in the window
+scene.jupyter = True
 
-# scene.render now will prepare the scene for rendering, 
-# but it won't render anything yet
+# scene.render now will prepare the scene for rendering, but it won't render anything yet
 scene.render()
 
-# to actually display the scene we use `vedo`'s `show` 
-# method to show the scene's actors
-show(scene.actors)
+# To display the scene we use `vedo`'s `show` method to show the scene's actors
+from vedo import Plotter  # <- this will be used to render an embedded scene 
+plt = Plotter()
+plt.show(*scene.renderables)  # same as vedo.show(*scene.renderables)
 ```
 
-and with `itkwidgets`:
-
-```python
-from ipywidgets import VBox, Button
-VBox([show(scene.actors)])
-```
-
-
-
+:::{hint}
+As with all BrainGlobe tools, if you do not have these atlases locally, the first time you run the commands 
+it may be slow as the data is downloaded.
+:::
\ No newline at end of file