Update tutorials (#514)

# References and relevant issues Related to #280 # Description Fixes a few typos, typesetting details. Updates content for the viewer tutorial, including new gui elements. Images will also need to be updated. --------- Co-authored-by: Peter Sobolewski <[email protected]> Co-authored-by: Draga Doncila Pop <[email protected]>
napari · Dec 14, 2024 · 930fe8d · 930fe8d
1 parent 13e944a
commit 930fe8d
Show file tree

Hide file tree

Showing 14 changed files with 84 additions and 65 deletions.
diff --git a/docs/_static/images/launch_cli_empty.png b/docs/_static/images/launch_cli_empty.png
diff --git a/docs/_static/images/launch_cli_image.png b/docs/_static/images/launch_cli_image.png
diff --git a/docs/_static/images/launch_ipython.png b/docs/_static/images/launch_ipython.png
diff --git a/docs/_static/images/launch_jupyter.png b/docs/_static/images/launch_jupyter.png
diff --git a/docs/_static/images/launch_script.png b/docs/_static/images/launch_script.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -189,6 +189,10 @@
         'http://app-model.readthedocs.io/en/latest/',
         'http://app-model.readthedocs.io/en/latest/objects.inv',
     ],
+    'vispy': [
+        'https://vispy.org/',
+        'https://vispy.org/objects.inv',
+    ],
 }
 
 myst_enable_extensions = [
@@ -197,6 +201,7 @@
     'substitution',
     'tasklist',
     'attrs_inline',
+    'linkify',
 ]
 
 myst_heading_anchors = 4

diff --git a/docs/tutorials/annotation/annotate_points.md b/docs/tutorials/annotation/annotate_points.md
@@ -354,7 +354,7 @@ For convenience, we can also define functions to increment and decrement the cur
 
 First, we define a function to increment to the next label and decorate it with the viewer key binding decorator.
 The decorator requires that we pass the key to bind the function to as a string and the decorated function should take an event as an input argument.
-In this case, we are binding `next_label()` to the `.` key.
+In this case, we are binding `next_label()` to the {kbd}`.` key.
 
 ```python
 @viewer.bind_key('.')
@@ -392,7 +392,7 @@ Like keybindings, we can also bind functions to mouse events such as clicking or
 Here, we create a function that will increment the label after a point is added (i.e., the mouse is clicked in the viewer canvas when in the point adding mode).
 This is convenient for quickly adding all labels to a frame, as one can simply click each feature in order without having to manually swap labels.
 To achieve this, we first check if the points layer is the the adding mode (`layer.mode == 'add'`).
-If so, we then reuse the next_label() function we defined above in the keybindings to increment the label.
+If so, we then reuse the `next_label()` function we defined above in the keybindings to increment the label.
 Finally,
 
 ```python
@@ -432,7 +432,7 @@ point_annotator(im_path, labels=['ear_l', 'ear_r', 'tail'])
 ### Saving the annotations
 
 Once we are happy with the annotations, we can save them to a CSV file using the builing CSV writer for the points layer.
-To do so, first, select the "Points" layer in the layer list and then click "Save Selected layer(s)"  in the "File" menu or press control+S (cmd+S on Mac OS)  to bring up the file save dialog.
+To do so, first, select the "Points" layer in the layer list and then click "Save Selected layer(s)"  in the "File" menu or press {kbd}`control+S` ({kbd}`cmd+S` on Mac OS)  to bring up the file save dialog.
 From here you can enter the file path and save the annotation coordinates as a CSV.
 
 ![Viewer with green box around a points layer in layer list. Label in green says "1. Select Points layer in the layer list". Dialog in the middle of the viewer has options to add save file name and choose save location, with Cancel and Save buttons in the bottom right.](../../_static/images/points_save_dialog.png)

diff --git a/docs/tutorials/fundamentals/getting_started.md b/docs/tutorials/fundamentals/getting_started.md
@@ -202,9 +202,9 @@ LD_LIBRARY_PATH="" napari
 ```
 
 If napari is successfully launched after this command, it means that on your machine
-the LD_LIBRARY_PATH environment variable is set to a directory that contains 
-a Qt dynamic dependency that is incompatible with the one that napari uses. 
-As linkers first search in LD_LIBRARY_PATH directories, this may cause napari to crash. 
+the `LD_LIBRARY_PATH` environment variable is set to a directory that contains
+a Qt dynamic dependency that is incompatible with the one that napari uses.
+As linkers first search in `LD_LIBRARY_PATH` directories, this may cause napari to crash.
 
 
 If you want to debug this issue for your specific use case, you 
@@ -224,7 +224,7 @@ Such import may raise an error like:
 
 ```
 ImportError: .../site-packages/PyQt5/QtWidgets.abi3.so: undefined symbol: _ZdlPvm, version Qt_5
-````
+```
 
 Then when you identify which file is causing the problem you can use `ldd` command
 to check which libraries are used by this file:

diff --git a/docs/tutorials/fundamentals/installation_bundle_conda.md b/docs/tutorials/fundamentals/installation_bundle_conda.md
@@ -70,7 +70,7 @@ The installation progress can be monitored on the following window. Some notific
 ![Cropped screenshot of the Installation page of the PKG installer. This page displays a progress bar at a 10%. In the top right corner, an example of a system notification with the text 'Installing packages. This might take a few minutes' is shown](../../_static/images/bundle_10.png)
 
 ```{note}
-If an error ocurred during the installation, do not close the installer immediately. Before doing so, please inspect the logs by clicking on Window > Installer log or pressing <kbd>⌘</kbd> + <kbd>L</kbd>. In the Detail Level dropdown, choose 'Show All Logs' and click on Save to keep a copy of the contents in a text file. This will be useful if you want to [submit an issue](https://github.com/napari/napari/issues/new/choose).
+If an error ocurred during the installation, do not close the installer immediately. Before doing so, please inspect the logs by clicking on Window > Installer log or pressing {kbd}`⌘+L`. In the Detail Level dropdown, choose 'Show All Logs' and click on Save to keep a copy of the contents in a text file. This will be useful if you want to [submit an issue](https://github.com/napari/napari/issues/new/choose).
 ```
 
 After finishing with no errors, a new page with the text "The installation was successful" will appear, as shown below.
@@ -82,7 +82,7 @@ Click Close to finish. You can now get started using napari! Use Launchpad to op
 ![Montage of two cropped screenshots. On the left, the macOS finder icon and the Launchpad icon, highlighted with a red circle. On the right, the opened launchpad UI showing a 4x4 grid of applications icon, with napari appearing in the bottom right corner.](../../_static/images/bundle_13.png)
 
 ```{note}
-The first time you open napari you must use the Launchpad, but in subsequent uses, the napari application should show up in Spotlight search (<kbd>⌘</kbd> + <kbd>spacebar</kbd>). The application shortcut will also be available in Finder, under 🏠 [User directory] > Applications.
+The first time you open napari you must use the Launchpad, but in subsequent uses, the napari application should show up in Spotlight search ({kbd}`⌘+spacebar`). The application shortcut will also be available in Finder, under 🏠 [User directory] > Applications.
 ```
 
 napari comes installed with sample images from scikit-image. Use the dropdown menu File > Open Sample > napari to open a sample image, or open one of your own images using File > Open or dragging and dropping your image onto the canvas.
@@ -127,17 +127,17 @@ Once you have downloaded the Linux SH file, you will have a file with a name lik
 
 ![Montage of the SH installer icon on Ubuntu, with an arrow pointing to an open terminal instance with a pre-typed command that reads 'bash napari-0.4.14.dev73-Linux-x86_64.sh'.](../../_static/images/bundle_28.png)
 
-Press <kbd>Enter</kbd> to display the License Agreement.
+Press {kbd}`Enter` to display the License Agreement.
 
 ![Cropped screenshot of the default Ubuntu terminal displaying the welcome paragraphs of the text-based installer of napari for Linux systems.](../../_static/images/bundle_29.png)
 
-Read through the agreement shown below. You must agree to the terms by typing out `yes` and pressing <kbd>Enter</kbd> to continue.
+Read through the agreement shown below. You must agree to the terms by typing out `yes` and pressing {kbd}`Enter` to continue.
 
 ![Cropped screenshot of the default Ubuntu terminal displaying the first paragraphs of a BSD-3 Clause License text.](../../_static/images/bundle_30.png)
 
 ![Cropped screenshot of the default Ubuntu terminal displaying the last paragraphs of a BSD-3 Clause License text, plus a prompt asking 'Do you accept the license terms?', to which the user must respond 'yes' or 'no'.](../../_static/images/bundle_31.png)
 
-Next you will be shown the default location for the installation. You may confirm this location by pressing <kbd>Enter</kbd>. Alternatively, specify a different location by typing out its absolute path. If it does not exist, it will be created. The terminal will then begin the installation process.
+Next you will be shown the default location for the installation. You may confirm this location by pressing {kbd}`Enter`. Alternatively, specify a different location by typing out its absolute path. If it does not exist, it will be created. The terminal will then begin the installation process.
 
 ![Montage of two instances of the default Ubuntu terminal showing the default installation path, followed by the first extraction steps of the installation process.](../../_static/images/bundle_32.png)
 

diff --git a/docs/tutorials/fundamentals/quick_start.md b/docs/tutorials/fundamentals/quick_start.md
@@ -24,8 +24,6 @@ napari is an open source project on [GitHub](https://github.com/napari/napari) t
 
 At its core, it provides critical viewer features out-of-the-box, such as support for [large multi-dimensional data](dask-napari); [“layers”](layers-glance) to simultaneously visualize images, models, and analysis results; and easy manual, interactive annotation in 3D.
 
-This tutorial uses napari 0.4.14. <br>
-
 +++
 
 ## What's covered here
@@ -82,21 +80,23 @@ Here we will be mainly focused on the GUI application.
 
 - From command line:
 
-    Once installed, simply run
-```python
+    Once installed, run
+```bash
 napari
 ```
 
 - If you installed the bundled app:
 
-    Click on the app icon to open it.<br>
+    Click on the app icon to open it.
+
     *Note: macOS users might need to right click on the app icon and select "Open" to bypass the security check. You can also go to System Settings > Privacy & Security and click on "Open Anyway".*
 
 +++
 
 ### Open an image
 
-napari natively supports tiff and many other formats supported by [skimage.io.imread](https://scikit-image.org/docs/dev/api/skimage.io.html) as input image file format.<br>
+napari natively supports tiff and many other formats supported by [skimage.io.imread](https://scikit-image.org/docs/dev/api/skimage.io.html) as input image file format.
+
 Try with your own images or download [this ome tiff file](https://downloads.openmicroscopy.org/images/OME-TIFF/2016-06/MitoCheck/00001_01.ome.tiff).
 
 Additional input file formats may be supported [by plugins](https://www.napari-hub.org/).
@@ -107,11 +107,11 @@ and select the image file, or simply drag and drop the image into napari.
 
 For demo purpose, we will use a sample image that comes with napari.
 
-(1) Open napari IPython console
+1. Open napari IPython console
 
 ![IPython console](../../_static/images/IPython.png)
 
-(2) Type
+2. Type
 
 ```python
 from skimage import data
@@ -155,7 +155,7 @@ nbscreenshot(viewer, alt_text="image of singular cell with yellow tint")
 ### Manually label the cell
 
 To measure the area of the cell, we can use a labels layer and manually "paint" the cell.
-The labels layer allows you to record the segmentation result by assigning background = 0, and assigning each object with an integer.
+The labels layer allows you to record the segmentation result by assigning `background = 0`, and assigning each object with an integer.
 
 1. Add a new labels layer
 1. Click on "paint"