Reorg of the Usage section of the docs #881

melissawm · 2025-10-30T00:21:23Z

References and relevant issues

N/A

Description

At the napari hackathon @ gloBIAS, we had the chance to discuss the docs organization with a few users and came up with ideas for potential improvements to our Usage section. We also discussed some changes to our API docs, but those will be handled separately.

~~This is a first very rough draft that is clearly incomplete, but I wanted to stash it somewhere so the work can continue.~~

EDIT: This is now ready for review. It only touches the first sections of the user guide but I think this is reasonable for now. This was discussed at the docs meeting this week (nov 20/21).

psobolewskiPhD · 2025-11-25T01:45:51Z

This is really great! 😍
Huge fan of breaking out the Layers into its own thing! This PR is the real closer to #42 😉

One thing that stand out to me:
Getting started > Open images is empty -- just a placeholder for now? Maybe we should copy paste something into it and flag it as a followup?
(the quickstart open an image could use a spruce up too probably)

brisvag · 2025-11-25T11:59:54Z

Love this work @melissawm! Much better than main :) Some thoughts:

Did we come up with a better name for the Features highlights section in the end?
I'd rename napari tutorial to something like case studies or in depth examples or walkthroughs. I'm also not sure if we want that there or lower down, but maybe we already discussed this?

DragaDoncila · 2025-11-26T03:24:57Z

as mentioned in docs meeting, I love this reorg ❤️ I dropped by because I noticed in the napari help menu we link to some of these guides, and I wanted to flag it in case we need to update any of those URLs. I don't think we do? Because it looks like it links to the file and we don't move the file. But just wanted to flag it and ask.

melissawm · 2025-11-29T18:00:27Z

Getting started > Open images is empty -- just a placeholder for now? Maybe we should copy paste something into it and flag it as a followup?

Exactly! I can remove this from the ToC for now but we do think this is important, and was something users brought up during the hackathon.

@DragaDoncila I will verify the help menu - good callout, I think we should be fine but we should check anyways. Worst case scenario we can also include redirects.

EDIT: Only the Getting Started link needs to change to "https://napari.org/{VERSION}/getting_started/start_index.html", here's the PR: napari/napari#8455

willingc · 2025-11-29T22:23:57Z

@melissawm Looks great. Not sure if in or out of scope, but I think we can shorten a few headings:

Shorten 'napari tutorials' to 'Tutorials'
Shorten 'napari workshops' to 'Workshops'
Shorten 'Layers User Guide' to 'Using layers'

melissawm · 2025-11-29T23:31:17Z

@willingc Thanks Carol! For tutorials and workshops I'm 💯 , for "Using layers" that's what we had before, and @TimMonko brought up something he saw on a talk which we agreed on, which is having the subject (layers in this case) be upfront in these titles so readers can skim better (Tim would you mind dropping a link here?)

However I'm not opposed to finding a shorter title if you have ideas! Maybe just "Layers guide"?

willingc · 2025-11-30T16:31:35Z

Layers Guide would be great. Thanks @melissawm and @TimMonko

willingc

Thanks @melissawm

willingc · 2025-11-30T16:33:34Z

@melissawm Maybe change the card to match Layers guide too. Same with Quickstart and Workshops.

docs/tutorials/cell_tracking.md

Czaki

I like this changes

melissawm · 2025-12-03T14:19:59Z

Updated!

guiwitz · 2025-12-05T08:21:40Z

Hi @melissawm. This looks great! BTW I created the docs locally using the pixi instructions and it worked really easily even though I'm not really a pixi user. I tried to go through the docs systematically and here are a few things I noticed:

Plugins: Plugins are mentioned in multiple places but there's never a paragraph to explain what they are or a link to the actual "Finding and installing plugins" page. For example in the Quickstart they are mentioned multiple times but the links only send to the hub or actual plugins pages. Same for the "Getting Started" section. For example plugins are mentioned in the in "Install" section but just to say that depending on how you install napari, certain plugins might not work. I have the impression a new user would go through these docs and not really understand this. I think plugins are not just some kind of optional additional thing you can do, but actually essential, e.g. they are required to open most non-tiff microscopy images. So my suggestion would be:
- in the "Quickstart", add a section "Plugins" quickly explaining what they are and sending readers to the actual plugin section
- in the "Getting Started -> Install napari" section add a specific part about installing plugins. I feel basic napari installation and plugin installation are tightly linked, so it would make sense to have it there. Again, no need to repeat content, but liking to the plugin page with minimum context would be sufficient.
Beginners: I still think that at the moment the introductory material contains too much code. The Quickstart has code, the Tour of the napari viewer has code etc. I fear this will turn away beginners who don't regularly code. I understand the goal of not duplicating information (e.g. showing how to use the layer list interactively and programmatically) but I think it would be useful to have at least a no-code simplified intro. Just as a simple example: if a user just wants to visualize some data in 3D (for which napari is really good), currently the 2d/3d toggling relies on importing data with code, while one could just import the demo cells3d image, show the 2D version, show the button, show the 3d version.
Open image: I'm happy to have a go at this if nobody else is working on it. Maybe in a new PR once this one is merged?

brisvag · 2025-12-05T09:36:42Z

All great points!

Open image: I'm happy to have a go at this if nobody else is working on it. Maybe in a new PR once this one is merged?

You can get started already if you want 😉

melissawm · 2025-12-05T12:19:28Z

Thank you so much @guiwitz ! Excellent points - I will try to address them in my next commit 😄

Czaki · 2025-12-16T11:04:21Z

bump

melissawm · 2025-12-20T22:37:01Z

Hello, folks! I tried addressing all the comments above. It may not be perfect but I'd like to merge this for 0.7.0 and we can continue improving in the meantime. I don't know how to solve the codespell errors though - the release notes seem to have some kind of formatting error at the source?

Anyway, @guiwitz if you can take a look soon that would be awesome. There is certainly room for improvements in all of these changes but at least we have a starting point.

Thanks!

psobolewskiPhD · 2025-12-22T20:47:11Z

docs/getting_started/quick_start.md

 (napari-quick-start)=

-# Quick start
+# Quickstart


My dictionary and my wife suggest this should be reverted to two words. cc: @napari/copy

Suggested change

# Quickstart

# Quick start

@psobolewskiPhD Both versions are now acceptable. Quickstart has become the norm for technical guides, while quick start means beginning quickly. I'm fine with either though would lean toward one word.

psobolewskiPhD · 2025-12-22T21:21:01Z

docs/getting_started/quick_start.md

 print('the cell area is: ', props[0].area)
 ```

 Alternatively, try [this plugin](https://www.napari-hub.org/plugins/napari-skimage-regionprops) to have the result in a table form.


The one linked here doesn't really work anymore as far as I can tell. Let's use the newer better one from Guillaume!

Suggested change

Alternatively, try [this plugin](https://napari-hub.org/plugins/napari-skimage.html) to use a GUI widget instead of the console.

psobolewskiPhD · 2025-12-22T21:29:01Z

docs/getting_started/installation.md

+
+Choose one of the options below to install napari as a Python package.
+
+::::::\{tab-set}


This tab set doesn't appear to be working in the Circle preview at least:

Ugh, yes. This is a weird side effect of the linter, something's messed up in those configs. I'll fix, thanks!

psobolewskiPhD · 2025-12-22T21:30:15Z

docs/getting_started/installation.md

+
+Click the tile below to jump to the installation instructions for your operating system.
+
+::::\{grid}


This grid isn't working in the Circle preview:

psobolewskiPhD · 2025-12-22T21:32:59Z

docs/getting_started/launch_napari.md


 ## Solving common problems

 ### napari does not launch with `No Qt bindings could be found`


For followup: we should move this to the Troubleshooting page and link that page here.

psobolewskiPhD · 2025-12-22T21:38:05Z

docs/getting_started/open_images.md

@@ -0,0 +1 @@
+# Open images in napari


copy-paste from quick start, just so it's not empty. We should make a follow-up issue to improve on this.

Suggested change

# Open images in napari

# Open images in napari

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/).

Try [napari-aicsimageio](https://www.napari-hub.org/plugins/napari-aicsimageio) if you have czi, lif, or nd2 files.

Once you have the proper plugin installed, use File > Open Files(s)

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.

### Option 1: Using the GUI to open an image

1. In napari, go to `File -> Open Sample -> napari built-ins -> Cell`

![Open sample image](../_static/images/open_image.png)

### Option 2: Using the napari console to open an image

1. Open napari IPython console

![IPython console](../_static/images/IPython.png)

2. Type

```python

from skimage import data

viewer.add_image(data.cell(), name='cell')

```

```{code-cell} ipython3

---

tags: [remove-input]

---

import napari

from napari.utils import nbscreenshot

viewer = napari.Viewer()

from skimage import data

viewer.add_image(data.cell(), name='cell')

nbscreenshot(viewer, alt_text="image of a single cell opened in napari viewer")

```

```{note}

Once you have a napari viewer open, you can also make a new `Image` layer from an image (or URL to an image) copied to your Clipboard using `File -> New Image from Clipboard` menu item (keybinding {kbd}`Command/Ctrl+N`).

```

psobolewskiPhD

This looks great! I left some minor comments, which arn't really blockers but nice to haves.

The real issue is the tiles and grids in getting_startedinstallation.md page not rendering right, at least in the circle previews.
It looks like the colon fencing (in place of backtick fencing) isn't working right, because other places look fine.

willingc · 2025-12-23T16:25:02Z

docs/usage.md

 annotation and analysis of large multi-dimensional images.

 ````{grid}
 ```{grid-item-card} napari quick start


@melissawm To keep things easy to scan and consistent across pages, I suggest simplifying the title of the card from "napari quick start" to "Quickstart".

github-actions bot assigned melissawm Oct 30, 2025

github-actions bot added the documentation Improvements or additions to documentation label Oct 30, 2025

melissawm added globias hackathon and removed documentation Improvements or additions to documentation labels Oct 30, 2025

melissawm force-pushed the usage-reorg branch from e4c5b99 to 1174f15 Compare November 22, 2025 12:47

github-actions bot added the documentation Improvements or additions to documentation label Nov 22, 2025

melissawm marked this pull request as ready for review November 22, 2025 12:52

melissawm mentioned this pull request Nov 29, 2025

Change link to getting started in Help menu napari/napari#8455

Draft

willingc approved these changes Nov 30, 2025

View reviewed changes

Czaki reviewed Dec 3, 2025

View reviewed changes

docs/tutorials/cell_tracking.md Outdated Show resolved Hide resolved

Czaki reviewed Dec 3, 2025

View reviewed changes

melissawm force-pushed the usage-reorg branch from 8d57535 to 139a628 Compare December 3, 2025 14:19

DragaDoncila added this to the 0.7.0 milestone Dec 11, 2025

melissawm added 4 commits December 20, 2025 18:25

WIP

a04e2e4

Lint

af7d7e1

Undo changes to release notes

00cf9e9

Changes from meeting

aed8d4b

melissawm added 4 commits December 20, 2025 18:25

Shorten some titles

8b13a53

Previous commit

80124a5

Address reviews

e26ddbb

Emphasize layers as data

6e2ca27

melissawm force-pushed the usage-reorg branch from 9aba60b to 6e2ca27 Compare December 20, 2025 21:25

melissawm added 2 commits December 20, 2025 18:41

Add release notes to fix CI failures

bdb572a

Improve quickstart, add plugins content

ea09288

psobolewskiPhD reviewed Dec 22, 2025

View reviewed changes

psobolewskiPhD requested changes Dec 22, 2025

View reviewed changes

Merge branch 'main' into usage-reorg

78c550d

willingc reviewed Dec 23, 2025

View reviewed changes


	Alternatively, try [this plugin](https://napari-hub.org/plugins/napari-skimage.html) to use a GUI widget instead of the console.


		Choose one of the options below to install napari as a Python package.

		::::::\{tab-set}


		Click the tile below to jump to the installation instructions for your operating system.

		::::\{grid}


		## Solving common problems

		### napari does not launch with `No Qt bindings could be found`

-# Open images in napari
+# Open images in napari
+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/).
+Try [napari-aicsimageio](https://www.napari-hub.org/plugins/napari-aicsimageio) if you have czi, lif, or nd2 files.
+Once you have the proper plugin installed, use File > Open Files(s)
+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.
+### Option 1: Using the GUI to open an image
+. In napari, go to `File -> Open Sample -> napari built-ins -> Cell`
+![Open sample image](../_static/images/open_image.png)
+### Option 2: Using the napari console to open an image
+. Open napari IPython console
+![IPython console](../_static/images/IPython.png)
+. Type
+```python
+from skimage import data
+viewer.add_image(data.cell(), name='cell')
+```
+```{code-cell} ipython3
+---
+tags: [remove-input]
+---
+import napari
+from napari.utils import nbscreenshot
+viewer = napari.Viewer()
+from skimage import data
+viewer.add_image(data.cell(), name='cell')
+nbscreenshot(viewer, alt_text="image of a single cell opened in napari viewer")
+```
+```{note}
+Once you have a napari viewer open, you can also make a new `Image` layer from an image (or URL to an image) copied to your Clipboard using `File -> New Image from Clipboard` menu item (keybinding {kbd}`Command/Ctrl+N`).
+```

Reorg of the Usage section of the docs #881

Are you sure you want to change the base?

Reorg of the Usage section of the docs #881

Uh oh!

Conversation

melissawm commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

References and relevant issues

Description

Uh oh!

psobolewskiPhD commented Nov 25, 2025

Uh oh!

brisvag commented Nov 25, 2025

Uh oh!

DragaDoncila commented Nov 26, 2025

Uh oh!

melissawm commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

willingc commented Nov 29, 2025

Uh oh!

melissawm commented Nov 29, 2025

Uh oh!

willingc commented Nov 30, 2025

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

willingc commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Czaki left a comment

Choose a reason for hiding this comment

Uh oh!

melissawm commented Dec 3, 2025

Uh oh!

guiwitz commented Dec 5, 2025

Uh oh!

brisvag commented Dec 5, 2025

Uh oh!

melissawm commented Dec 5, 2025

Uh oh!

Czaki commented Dec 16, 2025

Uh oh!

melissawm commented Dec 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

psobolewskiPhD left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

melissawm commented Oct 30, 2025 •

edited

Loading

melissawm commented Nov 29, 2025 •

edited

Loading

willingc commented Nov 30, 2025 •

edited

Loading