From de594975f9994c37f4b11a92d3951f887f9b9909 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Sun, 5 Oct 2025 23:35:36 -0500
Subject: [PATCH 1/5] update layer howtos

---
 docs/howtos/layers/image.md   | 24 ++++++++++++------------
 docs/howtos/layers/labels.md  | 15 ++++++++-------
 docs/howtos/layers/points.md  | 17 +++++++++--------
 docs/howtos/layers/shapes.md  | 17 +++++++++--------
 docs/howtos/layers/surface.md | 20 +++++++++++---------
 docs/howtos/layers/tracks.md  | 27 ++++++++++++++-------------
 docs/howtos/layers/vectors.md | 17 ++++++++---------
 7 files changed, 71 insertions(+), 66 deletions(-)

diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md
index a4cfece21..e90b9e0aa 100644
--- a/docs/howtos/layers/image.md
+++ b/docs/howtos/layers/image.md
@@ -100,10 +100,10 @@ The GUI controls may be adjusted as follows:
 
 ### A simple example
 
-Create a new viewer and add an image in one go using the {func}`napari.view_image`
+Create a new viewer and add an image in one go using the {func}`napari.imshow`
 function, or if you already have an existing viewer, add an image to it using
 `viewer.add_image`. The API for both methods is the same. In these examples
-we'll mainly use `view_image`.
+we'll mainly use `imshow`.
 
 A simple example of viewing an image is as follows:
 
@@ -112,7 +112,7 @@ import napari
 from skimage import data
 
 cells = data.cells3d()[30, 1]  # grab some data
-viewer = napari.view_image(cells, colormap='magma')
+viewer, layer = napari.imshow(cells, colormap='magma')
 ```
 
 ```{code-cell} python
@@ -129,15 +129,15 @@ nbscreenshot(viewer, alt_text="Cells")
 viewer.close()
 ```
 
-## Arguments of `view_image` and `add_image`
+## Arguments of `imshow` and `add_image`
 
-{meth}`~napari.view_layers.view_image` and {meth}`~napari.Viewer.add_image`
+{func}`napari.imshow` and {meth}`~napari.Viewer.add_image`
 accept the same layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_image)
+help(napari.imshow)
 ```
 
 ## Image data and NumPy-like arrays
@@ -234,10 +234,10 @@ from skimage import data
 cells = data.cells3d() #ZCYX image data
 
 # load multichannel image in one line
-viewer = napari.view_image(cells, channel_axis=1)
+viewer, layers = napari.imshow(cells, channel_axis=1)
 
 # load multichannel image in one line, with additional options
-viewer = napari.view_image(
+viewer, layers = napari.imshow(
     cells,
     channel_axis=1,
     name=["membrane", "nuclei"],
@@ -266,7 +266,7 @@ In this example, the `rgb` keyword is explicitly set to `True` because we know
 we are working with an `rgb` image:
 
 ```{code-cell} python
-viewer = napari.view_image(data.astronaut(), rgb=True)
+viewer, layer = napari.imshow(data.astronaut(), rgb=True)
 ```
 
 ```{code-cell} python
@@ -307,7 +307,7 @@ Pass any of these strings to set the image colormap as shown below:
 
 
 ```{code-cell} python
-viewer = napari.view_image(data.moon(), colormap='red')
+viewer, layer = napari.imshow(data.moon(), colormap='red')
 ```
 
 You can also access the current colormap through the `layer.colormap` property
@@ -331,7 +331,7 @@ from vispy.color import Colormap
 cmap = Colormap([[1, 0, 0], [0, 0, 0], [0, 0, 1]])
 image = cell()
 
-viewer = napari.view_image(image, colormap=('diverging', cmap))
+viewer, layer = napari.imshow(image, colormap=('diverging', cmap))
 ```
 
 ```{code-cell} python
@@ -374,7 +374,7 @@ an existing layer using the `contrast_limits` keyword argument or property,
 respectively.
 
 ```{code-cell} python
-viewer = napari.view_image(data.moon(), name='moon')
+viewer, layer = napari.imshow(data.moon(), name='moon')
 viewer.layers['moon'].contrast_limits=(100, 175)
 ```
 
diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md
index d4564e48e..9bd00df70 100644
--- a/docs/howtos/layers/labels.md
+++ b/docs/howtos/layers/labels.md
@@ -414,7 +414,7 @@ cause the undo history to be reset.
 ### A simple example
 
 Create a new viewer and add a labels image in one go using the
-{meth}`napari.view_labels` method. If you already have an existing viewer, you
+`viewer.add_labels` method. If you already have an existing viewer, you
 can add a `Labels` image to it using `viewer.add_labels`. The API for both
 methods is the same. In these examples we'll mainly use `add_labels` to overlay
 a `Labels` layer onto on image.
@@ -441,7 +441,7 @@ cleared = remove_small_objects(clear_border(bw), 20)
 label_image = label(cleared)
 
 # create the viewer and add the coins image
-viewer = napari.view_image(coins, name='coins')
+viewer, _ = napari.imshow(coins, name='coins')
 # add the labels
 labels_layer = viewer.add_labels(label_image, name='segmentation')
 ```
@@ -460,15 +460,16 @@ nbscreenshot(viewer, alt_text="Segmentation of coins in an image, displayed usin
 viewer.close()
 ```
 
-### Arguments of `view_labels` and `add_labels`
+### Arguments of `add_labels`
 
-{meth}`~napari.view_layers.view_labels` and {meth}`~napari.Viewer.add_labels`
-accept the same layer-creation parameters.
+{meth}`~napari.Viewer.add_labels`
+accepts the following layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_labels)
+# help on add_labels is available via the Viewer class
+help(napari.Viewer.add_labels)
 ```
 
 ### Labels data
@@ -534,7 +535,7 @@ from skimage import data
 from scipy import ndimage as ndi
 
 blobs = data.binary_blobs(length=128, volume_fraction=0.1, n_dim=3)
-viewer = napari.view_image(blobs.astype(float), name='blobs')
+viewer, _ = napari.imshow(blobs.astype(float), name='blobs')
 labeled = ndi.label(blobs)[0]
 labels_layer = viewer.add_labels(labeled, name='blob ID')
 viewer.dims.ndisplay = 3
diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md
index 93cfde415..b25480708 100644
--- a/docs/howtos/layers/points.md
+++ b/docs/howtos/layers/points.md
@@ -218,7 +218,7 @@ layer:
 ### A simple example
 
 You can create a new viewer and add a set of points in one go using the
-{meth}`napari.view_points` method, or if you already have an existing viewer,
+`viewer.add_points` method, or if you already have an existing viewer,
 you can add points to it using `viewer.add_points`. The API of both methods is
 the same. In these examples we'll mainly use `add_points` to overlay points onto
 on an existing image.
@@ -238,7 +238,7 @@ import napari
 import numpy as np
 from skimage import data
 
-viewer = napari.view_image(data.astronaut(), rgb=True)
+viewer, _ = napari.imshow(data.astronaut(), rgb=True)
 points = np.array([[100, 100], [200, 200], [300, 100]])
 
 points_layer = viewer.add_points(points, size=30)
@@ -258,15 +258,16 @@ nbscreenshot(viewer, alt_text="3 points overlaid on an astronaut image")
 viewer.close()
 ```
 
-### Arguments of `view_points` and `add_points`
+### Arguments of `add_points`
 
-{meth}`~napari.view_layers.view_points` and {meth}`~napari.Viewer.add_points`
-accept the same layer-creation parameters.
+{meth}`~napari.Viewer.add_points`
+accepts the following layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_points)
+# help on add_points is available via the Viewer class
+help(napari.Viewer.add_points)
 ```
 
 ### Points data
@@ -403,7 +404,7 @@ To do the same for a face color, substitute `face_color` for `border_color` in t
 example snippet below.
 
 ```{code-cell} python
-viewer = napari.view_image(data.astronaut(), rgb=True)
+viewer, _ = napari.imshow(data.astronaut(), rgb=True)
 points = np.array([[100, 100], [200, 200], [300, 100]])
 point_features = {
     'good_point': [True, True, False],
@@ -448,7 +449,7 @@ colormap on a feature. To do the same for a border color, substitute `face` for
 `border`.
 
 ```{code-cell} python
-viewer = napari.view_image(data.astronaut(), rgb=True)
+viewer, _ = napari.imshow(data.astronaut(), rgb=True)
 points = np.array([[100, 100], [200, 200], [300, 100]])
 point_features = {
     'good_point': [True, True, False],
diff --git a/docs/howtos/layers/shapes.md b/docs/howtos/layers/shapes.md
index a0a1b3295..2ee3031b2 100644
--- a/docs/howtos/layers/shapes.md
+++ b/docs/howtos/layers/shapes.md
@@ -341,7 +341,7 @@ are used. i.e. You can't remove a vertex before you have created a shape.
 ### A simple example
 
 You can create a new viewer and add a list of shapes in one go using the
-{meth}`napari.view_shapes` method, or if you already have an existing viewer,
+`viewer.add_shapes` method, or if you already have an existing viewer,
 you can add shapes to it using `viewer.add_shapes`. The API of both methods is
 the same. In these examples we'll mainly use `add_shapes` to overlay shapes onto
 an existing image.
@@ -369,7 +369,7 @@ building = np.array([[310, 382], [229, 381], [209, 401], [221, 411],
 polygons = [triangle, person, building]
 
 # add the image
-viewer = napari.view_image(data.camera(), name='photographer')
+viewer, _ = napari.imshow(data.camera(), name='photographer')
 
 # add the polygons
 shapes_layer = viewer.add_shapes(
@@ -395,15 +395,16 @@ nbscreenshot(viewer, alt_text="Shapes overlaid on image")
 viewer.close()
 ```
 
-### Arguments of `view_shapes` and `add_shapes`
+### Arguments of `add_shapes`
 
-{meth}`~napari.view_layers.view_shapes` and {meth}`~napari.Viewer.add_shapes`
-accept the same layer-creation parameters.
+{meth}`~napari.Viewer.add_shapes`
+accepts the following layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_shapes)
+# help on add_shapes is available via the Viewer class
+help(napari.Viewer.add_shapes)
 ```
 
 ### Shapes data
@@ -465,7 +466,7 @@ import numpy as np
 from skimage import data
 
 # add the image
-viewer = napari.view_image(data.camera(), name='photographer')
+viewer, _ = napari.imshow(data.camera(), name='photographer')
 
 # create a triangle
 triangle = np.array([[11, 13], [111, 113], [22, 246]])
@@ -513,7 +514,7 @@ import numpy as np
 from skimage import data
 
 # add the image
-viewer = napari.view_image(data.camera(), name='photographer')
+viewer, _ = napari.imshow(data.camera(), name='photographer')
 
 # create some ellipses
 ellipse = np.array([[59, 222], [110, 289], [170, 243], [119, 176]])
diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md
index 8023adb44..77d98ba0c 100644
--- a/docs/howtos/layers/surface.md
+++ b/docs/howtos/layers/surface.md
@@ -39,10 +39,8 @@ colormap.
 
 ## A simple example
 
-You can create a new viewer and add a surface in one go using the
-{meth}`napari.view_surface` method, or if you already have an existing viewer,
-you can add an image to it using `viewer.add_surface`. The API of both methods
-is the same. In these examples we'll mainly use `view_surface`.
+You can create a new viewer and add a surface using the
+{meth}`~napari.Viewer.add_surface` method. In these examples we'll mainly use `viewer.add_surface`.
 
 A simple example of viewing a surface follows. You can copy and paste these
 statements into the napari console to see how they work:
@@ -56,7 +54,10 @@ faces = np.array([[0, 1, 2], [1, 2, 3]])
 values = np.linspace(0, 1, len(vertices))
 surface = (vertices, faces, values)
 
-viewer = napari.view_surface(surface)  # add the surface
+```python
+viewer = napari.Viewer()
+viewer.add_surface(surface)  # add the surface
+```
 ```
 
 ```{code-cell} python
@@ -102,15 +103,16 @@ controls are available in the viewer:
     section of _Layers at a glance_ for an explanation of each type of blending.
   * Shading - Choose `none`, `flat`, or `smooth` from the dropdown.
 
-## Arguments of `view_surface` and `add_surface`
+## Arguments of `add_surface`
 
-{meth}`~napari.view_layers.view_surface` and {meth}`~napari.Viewer.add_surface`
-accept the same layer-creation parameters.
+{meth}`~napari.Viewer.add_surface` accepts the following layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_surface)
+```python
+# help(napari.Viewer.add_surface)  # see the add_surface method
+```
 ```
 
 ## Surface data
diff --git a/docs/howtos/layers/tracks.md b/docs/howtos/layers/tracks.md
index 80d05c264..bb088863e 100644
--- a/docs/howtos/layers/tracks.md
+++ b/docs/howtos/layers/tracks.md
@@ -39,9 +39,7 @@ class/type.
 
 ## A simple example
 
-You can create a new viewer and add a set of tracks in one go using {func}`napari.view_tracks`,
-or if you already have an existing viewer, you can add tracks to it using {meth}`viewer.add_tracks<napari.Viewer.add_tracks>`.
-The API of both methods is the same.
+You can create a new viewer and add a set of tracks using using {meth}`viewer.add_tracks<napari.Viewer.add_tracks>`.
 
 In this example, we will overlay some tracks on an image from the Hubble space
 telescope:
@@ -70,7 +68,7 @@ tracks_data = [
     [3, 4, 636, 1000]
 ]
 
-viewer = napari.view_image(hubble_image, name='image')
+viewer, _ = napari.imshow(hubble_image, name='image')
 viewer.add_tracks(tracks_data, name='tracks')
 
 napari.run()
@@ -164,7 +162,8 @@ tracks_data = [
     [1, 1, 10, 8, 7]
 ]
 
-viewer = napari.view_tracks(tracks_data)
+viewer = napari.Viewer()
+viewer.add_tracks(tracks_data)
 napari.run()
 ```
 
@@ -220,13 +219,14 @@ other high dimensional data.
 ## Changing track width
 
 We can specify the width of the tracks in pixels. The track width can be
-specified via the `tail_width` keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and
-`napari.view_tracks()` methods. From a layer that has already been constructed,
+specified via the `tail_width` keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` method. 
+From a layer that has already been constructed,
 we can set the track width via the `layer.tail_width` property.
 
 ```python
 # create a tracks layer with a tail width of 5 pixels
-viewer = napari.view_tracks(data, tail_width=5, name="my_tracks")
+viewer = napari.Viewer()
+viewer.add_tracks(data, tail_width=5, name="my_tracks")
 
 # update the tail width to 3 pixels
 viewer.layers["my_tracks"].tail_width = 3
@@ -253,13 +253,14 @@ Additionally, we can adjust the width of the track in the GUI using the
 We can specify the length of the tails of the tracks in time units. The tail is
 the portion of the track displayed from previous time steps. The track tail
 length can be specified via the `tail_length` keyword argument in the
-{meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and `napari.view_tracks()` methods. From a layer that has
+{meth}`viewer.add_tracks<napari.Viewer.add_tracks>` method. From a layer that has
 already been constructed, we can set the track width via the `tail_length`
 property.
 
 ```python
 # create a tracks layer with a tail length of 5 time units
-viewer = napari.view_tracks(data, tail_length=5, name="my_tracks")
+viewer = napari.Viewer()
+viewer.add_tracks(data, tail_length=5, name="my_tracks")
 
 # update the tail width to 3 pixels
 viewer.layers["my_tracks"].tail_length = 3
@@ -286,8 +287,8 @@ length" slider in the `tracks` layer controls.
 
 We can color the tracks by mapping colors to the track features defined in
 `Tracks.features`. If we define features and pass them via the `features`
-keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and `napari.view_tracks()`
-methods, we can then select the feature we would like to color the tracks by in
+keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>`
+method, we can then select the feature we would like to color the tracks by in
 the "color by" dropdown menu in the `tracks` layer controls. We can additionally
 specify the colormap used to map the feature value to color via the "colormap"
 dropdown menu.
@@ -322,7 +323,7 @@ features = {
     'confidence': track_confidence
 }
 
-viewer = napari.view_image(hubble_image)
+viewer, _ = napari.imshow(hubble_image)
 viewer.add_tracks(tracks_data, features=features)
 napari.run()
 ```
diff --git a/docs/howtos/layers/vectors.md b/docs/howtos/layers/vectors.md
index 717a0e729..5ee4cbc4f 100644
--- a/docs/howtos/layers/vectors.md
+++ b/docs/howtos/layers/vectors.md
@@ -36,10 +36,8 @@ the console or from the GUI.
 
 ## A simple example
 
-You can create a new viewer and add vectors in one go using the
-{meth}`napari.view_vectors` method, or if you already have an existing viewer,
-you can add vectors to it using `viewer.add_vectors`. The API of both methods is
-the same. In these examples we'll mainly use `add_vectors` to overlay vectors
+You can create a new viewer and add vectors using the
+{meth}`~napari.Viewer.add_vectors` method. In these examples we'll mainly use `add_vectors` to overlay vectors
 onto an existing image.
 
 In this example, we will overlay vectors on the image of a photographer:
@@ -61,7 +59,7 @@ vectors[:, 1, 1] = radius_space * np.sin(phi_space)
 vectors[:, 0] = vectors[:, 1] + 256
 
 # add the image
-viewer = napari.view_image(data.camera(), name='photographer')
+viewer, _ = napari.imshow(data.camera(), name='photographer')
 # add the vectors
 vectors_layer = viewer.add_vectors(vectors, edge_width=3)
 ```
@@ -150,15 +148,16 @@ both 2D and 3D:
 </figure>
 ```
 
-## Arguments of `view_vectors` and `add_vectors`
+## Arguments of `add_vectors`
 
-{meth}`~napari.view_layers.view_vectors` and {meth}`~napari.Viewer.add_vectors`
-accept the same layer-creation parameters.
+{meth}`~napari.Viewer.add_vectors` accepts the following layer-creation parameters.
 
 ```{code-cell} python
 :tags: [hide-output]
 
-help(napari.view_vectors)
+```python
+# help(napari.Viewer.add_vectors)  # see the add_vectors method
+```
 ```
 
 ### Changing vector length, width, and color

From 86f8b00f5cd25874f0210c8a5c999b037d625771 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Sun, 5 Oct 2025 23:36:01 -0500
Subject: [PATCH 2/5] update tutorials

---
 docs/tutorials/annotation/annotate_points.md         |  4 ++--
 docs/tutorials/processing/dask.md                    | 10 +++++-----
 docs/tutorials/segmentation/annotate_segmentation.md |  8 ++++----
 docs/tutorials/tracking/cell_tracking.md             |  3 ++-
 4 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/docs/tutorials/annotation/annotate_points.md b/docs/tutorials/annotation/annotate_points.md
index adfab3471..b51780d11 100644
--- a/docs/tutorials/annotation/annotate_points.md
+++ b/docs/tutorials/annotation/annotate_points.md
@@ -119,7 +119,7 @@ def point_annotator(
     """
     stack = imread(im_path)
 
-    viewer = napari.view_image(stack)
+    viewer, layer = napari.imshow(stack)
     points_layer = viewer.add_points(
         ndim=3,
         features=pd.DataFrame({'label': pd.Categorical([], categories=labels)}),
@@ -212,7 +212,7 @@ stack = imread(im_path)
 We can then start the viewer.
 
 ```python
-viewer = napari.view_image(stack)
+viewer, layer = napari.imshow(stack)
 napari.run()
 ```
 
diff --git a/docs/tutorials/processing/dask.md b/docs/tutorials/processing/dask.md
index 99a487a06..28a62f80f 100644
--- a/docs/tutorials/processing/dask.md
+++ b/docs/tutorials/processing/dask.md
@@ -96,7 +96,7 @@ stack
 *No data has been read from disk yet!*
 
 `napari` is capable of consuming Dask arrays,
-so you can simply call `napari.view_image` on this `stack` and behind the scenes,
+so you can simply call `napari.imshow` on this `stack` and behind the scenes,
 Dask will take care of reading the data from disk
 and handing a `numpy` array to `napari` each time a new timepoint or channel is requested.
 
@@ -105,7 +105,7 @@ import napari
 
 # specify contrast_limits and multiscale=False with big data
 # to avoid unnecessary computations
-napari.view_image(stack, contrast_limits=[0,2000], multiscale=False)
+napari.imshow(stack, contrast_limits=[0,2000], multiscale=False)
 ```
 
 *Note: providing the* `contrast_limits` *and* `multiscale` *arguments prevents* `napari` *from trying to calculate the data min/max, which can take an extremely long time with big data.
@@ -127,7 +127,7 @@ import napari
 from dask_image.imread import imread
 
 stack = imread("/path/to/experiment/*.tif")
-napari.view_image(stack, contrast_limits=[0,2000], multiscale=False)
+napari.imshow(stack, contrast_limits=[0,2000], multiscale=False)
 ```
 
 ```{raw} html
@@ -219,7 +219,7 @@ from dask_image.imread import imread
 images = imread(
     'SYNTHESIZED_TIFF_Images_Raw/Synthesized_FLASH25_100um_TIFF_Axial_Images/Synthesized_FLASH25_Axial_*.tiff'
     )
-napari.view_image(images)
+napari.imshow(images)
 
 if __name__ == '__main__':
     napari.run()
@@ -286,7 +286,7 @@ cropped = deconvolved.map_blocks(crop, dtype="float32")
 
 # put the resulting dask array into napari.
 # (don't forget the contrast limits and multiscale==False !)
-v = napari.view_image(
+viewer, _ = napari.imshow(
     cropped,
     contrast_limits=[90, 1500],
     multiscale=False,
diff --git a/docs/tutorials/segmentation/annotate_segmentation.md b/docs/tutorials/segmentation/annotate_segmentation.md
index 9ad6b91b0..5f501c7bf 100644
--- a/docs/tutorials/segmentation/annotate_segmentation.md
+++ b/docs/tutorials/segmentation/annotate_segmentation.md
@@ -121,7 +121,7 @@ text_parameters = {
 }
 
 # initialise viewer with coins image
-viewer = napari.view_image(image, name='coins', rgb=False)
+viewer, _ = napari.imshow(image, name='coins', rgb=False)
 
 # add the labels
 label_layer = viewer.add_labels(label_image, name='segmentation')
@@ -178,7 +178,7 @@ image = data.coins()[50:-50, 50:-50]
 label_image = segment(image)
 
 # initialize viewer with coins image
-viewer = napari.view_image(image, name='coins', rgb=False)
+viewer, _ = napari.imshow(image, name='coins', rgb=False)
 
 # add the labels
 label_layer = viewer.add_labels(label_image, name='segmentation')
@@ -296,7 +296,7 @@ As we saw above in the segmentation section, we can visualize the original image
 
 ```python
 # initialise viewer with coins image
-viewer = napari.view_image(image, name='coins', rgb=False)
+viewer, _ = napari.imshow(image, name='coins', rgb=False)
 
 # add the labels
 label_layer = viewer.add_labels(label_image, name='segmentation')
@@ -385,7 +385,7 @@ text_kwargs = {
 }
 
 # initialise viewer with coins image
-viewer = napari.view_image(image, name='coins', rgb=False)
+viewer, _ = napari.imshow(image, name='coins', rgb=False)
 
 # add the labels
 label_layer = viewer.add_labels(label_image, name='segmentation')
diff --git a/docs/tutorials/tracking/cell_tracking.md b/docs/tutorials/tracking/cell_tracking.md
index 11c3ac83c..87cfde5e8 100644
--- a/docs/tutorials/tracking/cell_tracking.md
+++ b/docs/tutorials/tracking/cell_tracking.md
@@ -85,7 +85,8 @@ At this point, there is no concept of track *links*, lineages, or tracks splitti
 These single tracks are sometimes known as tracklets:
 
 ```python
-napari.view_tracks(data, name='tracklets')
+viewer = napari.Viewer()
+viewer.add_tracks(data, name='tracklets')
 napari.run()
 ```
 

From 7ed932b556da8e67e042cd1ad9a4c56552d02d94 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Sun, 5 Oct 2025 23:36:50 -0500
Subject: [PATCH 3/5] update remaining guides

---
 docs/guides/layers.md             | 2 +-
 docs/howtos/extending/magicgui.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/guides/layers.md b/docs/guides/layers.md
index c5c646877..5f55d70be 100644
--- a/docs/guides/layers.md
+++ b/docs/guides/layers.md
@@ -188,7 +188,7 @@ existing layer using the `scale` as a keyword argument or property respectively.
 
 ```python
 # scaling while creating the image layer
-napari.view_image(retina, name='retina', scale=[1,10,1,1])
+viewer, layer = napari.imshow(retina, name='retina', scale=[1,10,1,1])
 # scaling an existing layer
 viewer.layers['retina'].scale = [1,10,1,1]
 ```
diff --git a/docs/howtos/extending/magicgui.md b/docs/howtos/extending/magicgui.md
index 74404e6fb..32103ff6c 100644
--- a/docs/howtos/extending/magicgui.md
+++ b/docs/howtos/extending/magicgui.md
@@ -143,7 +143,7 @@ def threshold_magic_widget(
     return img_as_float(img_layer.data) > threshold
 
 # Create the viewer and add an image
-viewer = napari.view_image(data.camera())
+viewer, _ = napari.imshow(data.camera())
 # Add widget to viewer
 viewer.window.add_dock_widget(threshold_magic_widget)
 ```
@@ -303,7 +303,7 @@ from napari.layers import Image
 def my_widget(image: Image):
     ...
 
-viewer = napari.view_image(np.random.rand(64, 64), name="My Image")
+viewer, _ = napari.imshow(np.random.rand(64, 64), name="My Image")
 viewer.window.add_dock_widget(my_widget)
 ```
 *Note the widget on the right side with "My Image" as the currently selected option*
@@ -508,7 +508,7 @@ def threshold(image: ImageData, threshold: int = 75) -> LabelsData:
     """Threshold an image and return a mask."""
     return (image > threshold).astype(int)
 
-viewer = napari.view_image(np.random.randint(0, 100, (64, 64)))
+viewer, _ = napari.imshow(np.random.randint(0, 100, (64, 64)))
 viewer.window.add_dock_widget(threshold)
 threshold()  # "call the widget" to call the function, so it shows in the
              # screenshot below.

From efe4657e5cd6cb19323a56c83c6318f2b1623389 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Sun, 5 Oct 2025 23:36:59 -0500
Subject: [PATCH 4/5] update dev docs

---
 docs/developers/architecture/app_model.md              | 3 ++-
 docs/developers/contributing/documentation/index.md    | 2 +-
 docs/developers/contributing/performance/benchmarks.md | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/developers/architecture/app_model.md b/docs/developers/architecture/app_model.md
index fcffb3148..5ea6dbf8f 100644
--- a/docs/developers/architecture/app_model.md
+++ b/docs/developers/architecture/app_model.md
@@ -437,7 +437,8 @@ Our provider was context dependent. Only when we have an active viewer with a
 points layer, can it be provided:
 
 ```python
->>> viewer = napari.view_points(name='Some Points')
+>>> viewer = napari.Viewer()
+>>> viewer.add_points(name='Some Points')
 
 >>> injected_func()
 Some Points
diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md
index 7205710e1..99e82c4ee 100644
--- a/docs/developers/contributing/documentation/index.md
+++ b/docs/developers/contributing/documentation/index.md
@@ -775,7 +775,7 @@ from skimage import data
 import napari
 
 # create the viewer with an image
-viewer = napari.view_image(data.astronaut(), rgb=True)
+viewer, _ = napari.imshow(data.astronaut(), rgb=True)
 
 if __name__ == '__main__':
     napari.run()
diff --git a/docs/developers/contributing/performance/benchmarks.md b/docs/developers/contributing/performance/benchmarks.md
index 9cce3ab11..27b1bf52d 100644
--- a/docs/developers/contributing/performance/benchmarks.md
+++ b/docs/developers/contributing/performance/benchmarks.md
@@ -67,7 +67,7 @@ class ViewImageSuite:
 
     def time_view_image(self):
         """Time to view an image."""
-        self.viewer = napari.view_image(self.data)
+        self.viewer, _ = napari.imshow(self.data)
 ```
 
 Here, the creation of the image is completed in the ``setup`` method, and not

From 2e92518be0e3e043fcf6145e2dc867e16217db0b Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Mon, 6 Oct 2025 12:18:36 -0500
Subject: [PATCH 5/5] fix errors and editing pass

---
 docs/developers/contributing/documentation/index.md |  2 +-
 docs/guides/layers.md                               |  4 +++-
 docs/howtos/layers/image.md                         |  2 +-
 docs/howtos/layers/labels.md                        |  7 ++-----
 docs/howtos/layers/points.md                        |  8 ++------
 docs/howtos/layers/shapes.md                        |  9 +++------
 docs/howtos/layers/surface.md                       | 10 +++-------
 docs/howtos/layers/tracks.md                        |  4 ++--
 docs/howtos/layers/vectors.md                       | 10 ++++------
 docs/tutorials/annotation/annotate_points.md        |  4 ++--
 10 files changed, 23 insertions(+), 37 deletions(-)

diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md
index 99e82c4ee..a746af0ff 100644
--- a/docs/developers/contributing/documentation/index.md
+++ b/docs/developers/contributing/documentation/index.md
@@ -775,7 +775,7 @@ from skimage import data
 import napari
 
 # create the viewer with an image
-viewer, _ = napari.imshow(data.astronaut(), rgb=True)
+viewer, layer = napari.imshow(data.astronaut(), rgb=True)
 
 if __name__ == '__main__':
     napari.run()
diff --git a/docs/guides/layers.md b/docs/guides/layers.md
index 5f55d70be..b9cc3e506 100644
--- a/docs/guides/layers.md
+++ b/docs/guides/layers.md
@@ -189,8 +189,10 @@ existing layer using the `scale` as a keyword argument or property respectively.
 ```python
 # scaling while creating the image layer
 viewer, layer = napari.imshow(retina, name='retina', scale=[1,10,1,1])
-# scaling an existing layer
+# scaling an existing layer by accessing from the layer list
 viewer.layers['retina'].scale = [1,10,1,1]
+# alternatively using the returned layer variable
+layer.scale = [1,10,1,1]
 ```
 
 ```{raw} html
diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md
index e90b9e0aa..a3e12f677 100644
--- a/docs/howtos/layers/image.md
+++ b/docs/howtos/layers/image.md
@@ -112,7 +112,7 @@ import napari
 from skimage import data
 
 cells = data.cells3d()[30, 1]  # grab some data
-viewer, layer = napari.imshow(cells, colormap='magma')
+viewer, _ = napari.imshow(cells, colormap='magma')
 ```
 
 ```{code-cell} python
diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md
index 9bd00df70..d877dd945 100644
--- a/docs/howtos/layers/labels.md
+++ b/docs/howtos/layers/labels.md
@@ -413,10 +413,8 @@ cause the undo history to be reset.
 ## Controlling the `labels` layer from the console
 ### A simple example
 
-Create a new viewer and add a labels image in one go using the
-`viewer.add_labels` method. If you already have an existing viewer, you
-can add a `Labels` image to it using `viewer.add_labels`. The API for both
-methods is the same. In these examples we'll mainly use `add_labels` to overlay
+Create a new viewer with `napari.Viewer()` and then add a labels image in one go using the {meth}`~napari.Viewer.add_labels` method.
+In these examples we'll mainly use `add_labels` to overlay
 a `Labels` layer onto on image.
 
 In this example of instance segmentation, we will find and segment each of the
@@ -468,7 +466,6 @@ accepts the following layer-creation parameters.
 ```{code-cell} python
 :tags: [hide-output]
 
-# help on add_labels is available via the Viewer class
 help(napari.Viewer.add_labels)
 ```
 
diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md
index b25480708..752451b9a 100644
--- a/docs/howtos/layers/points.md
+++ b/docs/howtos/layers/points.md
@@ -217,11 +217,8 @@ layer:
 ## Controlling the `points` layer programmatically
 ### A simple example
 
-You can create a new viewer and add a set of points in one go using the
-`viewer.add_points` method, or if you already have an existing viewer,
-you can add points to it using `viewer.add_points`. The API of both methods is
-the same. In these examples we'll mainly use `add_points` to overlay points onto
-on an existing image.
+You can create a new viewer with `napari.Viewer()` and add a set of points with the `viewer.add_points` method.
+In these examples we'll mainly use `add_points` to overlay points onto an existing image.
 
 Each data point can have annotations associated with it using the
 `Points.features` table. These features can be used to set the face and
@@ -266,7 +263,6 @@ accepts the following layer-creation parameters.
 ```{code-cell} python
 :tags: [hide-output]
 
-# help on add_points is available via the Viewer class
 help(napari.Viewer.add_points)
 ```
 
diff --git a/docs/howtos/layers/shapes.md b/docs/howtos/layers/shapes.md
index 2ee3031b2..550114791 100644
--- a/docs/howtos/layers/shapes.md
+++ b/docs/howtos/layers/shapes.md
@@ -340,11 +340,9 @@ are used. i.e. You can't remove a vertex before you have created a shape.
 ## Controlling the shapes layer programmatically
 ### A simple example
 
-You can create a new viewer and add a list of shapes in one go using the
-`viewer.add_shapes` method, or if you already have an existing viewer,
-you can add shapes to it using `viewer.add_shapes`. The API of both methods is
-the same. In these examples we'll mainly use `add_shapes` to overlay shapes onto
-an existing image.
+You can create a new viewer with `napari.Viewer()` and add a list of shapes with the
+`viewer.add_shapes` method.
+In these examples we'll mainly use `add_shapes` to overlay shapes onto an existing image.
 
 In this example, we will overlay shapes on the image of a photographer:
 
@@ -403,7 +401,6 @@ accepts the following layer-creation parameters.
 ```{code-cell} python
 :tags: [hide-output]
 
-# help on add_shapes is available via the Viewer class
 help(napari.Viewer.add_shapes)
 ```
 
diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md
index 77d98ba0c..b61bf0803 100644
--- a/docs/howtos/layers/surface.md
+++ b/docs/howtos/layers/surface.md
@@ -39,8 +39,8 @@ colormap.
 
 ## A simple example
 
-You can create a new viewer and add a surface using the
-{meth}`~napari.Viewer.add_surface` method. In these examples we'll mainly use `viewer.add_surface`.
+You can create a new viewer with `napari.Viewer()` and add a surface using the
+{meth}`~napari.Viewer.add_surface` method.
 
 A simple example of viewing a surface follows. You can copy and paste these
 statements into the napari console to see how they work:
@@ -54,11 +54,9 @@ faces = np.array([[0, 1, 2], [1, 2, 3]])
 values = np.linspace(0, 1, len(vertices))
 surface = (vertices, faces, values)
 
-```python
 viewer = napari.Viewer()
 viewer.add_surface(surface)  # add the surface
 ```
-```
 
 ```{code-cell} python
 :tags: [hide-input]
@@ -110,9 +108,7 @@ controls are available in the viewer:
 ```{code-cell} python
 :tags: [hide-output]
 
-```python
-# help(napari.Viewer.add_surface)  # see the add_surface method
-```
+help(napari.Viewer.add_surface)
 ```
 
 ## Surface data
diff --git a/docs/howtos/layers/tracks.md b/docs/howtos/layers/tracks.md
index bb088863e..27680523f 100644
--- a/docs/howtos/layers/tracks.md
+++ b/docs/howtos/layers/tracks.md
@@ -39,7 +39,7 @@ class/type.
 
 ## A simple example
 
-You can create a new viewer and add a set of tracks using using {meth}`viewer.add_tracks<napari.Viewer.add_tracks>`.
+You can create a new viewer with `napari.Viewer()` and add a set of tracks using using {meth}`viewer.add_tracks<napari.Viewer.add_tracks>`.
 
 In this example, we will overlay some tracks on an image from the Hubble space
 telescope:
@@ -219,7 +219,7 @@ other high dimensional data.
 ## Changing track width
 
 We can specify the width of the tracks in pixels. The track width can be
-specified via the `tail_width` keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` method. 
+specified via the `tail_width` keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` method.
 From a layer that has already been constructed,
 we can set the track width via the `layer.tail_width` property.
 
diff --git a/docs/howtos/layers/vectors.md b/docs/howtos/layers/vectors.md
index 5ee4cbc4f..1a4460b79 100644
--- a/docs/howtos/layers/vectors.md
+++ b/docs/howtos/layers/vectors.md
@@ -36,9 +36,9 @@ the console or from the GUI.
 
 ## A simple example
 
-You can create a new viewer and add vectors using the
-{meth}`~napari.Viewer.add_vectors` method. In these examples we'll mainly use `add_vectors` to overlay vectors
-onto an existing image.
+You can create a new viewer with `napari.Viewer()` and add vectors using the
+{meth}`~napari.Viewer.add_vectors` method.
+In these examples we'll mainly use `add_vectors` to overlay vectors onto an existing image.
 
 In this example, we will overlay vectors on the image of a photographer:
 
@@ -155,9 +155,7 @@ both 2D and 3D:
 ```{code-cell} python
 :tags: [hide-output]
 
-```python
-# help(napari.Viewer.add_vectors)  # see the add_vectors method
-```
+help(napari.Viewer.add_vectors)
 ```
 
 ### Changing vector length, width, and color
diff --git a/docs/tutorials/annotation/annotate_points.md b/docs/tutorials/annotation/annotate_points.md
index b51780d11..db287000b 100644
--- a/docs/tutorials/annotation/annotate_points.md
+++ b/docs/tutorials/annotation/annotate_points.md
@@ -119,7 +119,7 @@ def point_annotator(
     """
     stack = imread(im_path)
 
-    viewer, layer = napari.imshow(stack)
+    viewer, _ = napari.imshow(stack)
     points_layer = viewer.add_points(
         ndim=3,
         features=pd.DataFrame({'label': pd.Categorical([], categories=labels)}),
@@ -212,7 +212,7 @@ stack = imread(im_path)
 We can then start the viewer.
 
 ```python
-viewer, layer = napari.imshow(stack)
+viewer, _ = napari.imshow(stack)
 napari.run()
 ```