---
# System prepended metadata

title: napari Documentation Working Group meeting notes
tags: [docs]

---

# napari Documentation Working Group meeting notes

- Zoom meeting: https://numfocus-org.zoom.us/j/85478605022?pwd=JAIWzoSLu3bkxbWaYFpV80tyR6lIS9.1
- Link to this HackMD: https://hackmd.io/@napari/docs-wg
- Project board: https://github.com/orgs/napari/projects/31

## 2026-01-29/30

Attendees: Tim, Draga, Juan

### Topics

- add your topics here :)
- Scalebar https://github.com/napari/docs/issues/38
    - Tim pair up with Margot on adding to API
        - we need to add the scale_bar class to the API
        - viewer.componenets expose Overlays
    - Potentially pair up to add a new "Viewer Overlays"  about the scalebar
    
        - xref the scalebar example
    - Looking at how we can expose the `ScaleBarOverlay` in the components.rst
    - 
- Guillaume's open image PR

## 2026-01-15/16

Attendees: Tim, Draga, Melissa

### Topics

- Tim: Guillaume's #907 on open images getting started
    - Add to docs contributing guide, adominition to ping core team / open PR napari/napari to change the dependency-group
    - The docs contributing guide is too long for Melissa
    - follow-up issue for Open File, Open Files..., etc (what is all the different behavior)
    - Address CI issues
    - Add a card to the getting started index
    - Take out the metadata part of my plugin, and just make a follow-up issue for when napari-metadata is ready
- Tim: My migration of napari-hub wiki info to the docs #906 - any other info that needs converted over? 
    - currently under Testing and Publishing -> Customizing your listing
    - should it be exposed more?
        - could go on hub-lite somewhere?
        - we link to it from napari-plugin-template output and in the readme
        - could be its own card on the "Plugin developers" section?
        - move "Virtual environments and useful tools" card to the end, and slot in "Customizing your plugin's listing"
        - get rid of .napari-hub/ information
    - PLUGIN VISIBILITY DOESNT WORK, make follow-up issue to include once its fixed 
- consider removing "the tools and tips firehouse page" - consider for part of the reorg plugin section

### Action Items

- Tim: Make reorganization of plugin section issue
- Tim: citation.cff feature request for hub-lite, link back to this PR/doc
- Tim: make issue for hub-lite review .napari-hub/ and consider how to transform
- Tim: make PR to napari-plugin-template to remove .napari-hub/ for the template 
- Tim: add docs dependency info to docs PR template 
- Draga: Update npe2api/#32 and get it merged
    - check if we need historical updates for hidden plugins that we already show
- Tim: Add to npe2api contribution.md the interaction with deploying the plugin index


## 2025-12-18/19

### Attendees

- Draga

### Topics

- PRs for 0.7.0
    - #881 - Usage reorg
        - Melissa will try to update before the break
    - 

## 2025-12-04/05

### Attendees

- Melissa, Juan, Carolyn, Tim

### Topics

- Follow-up from last meeting:
    - Capture discussion around installation guide in one issue?
    - Proposal for reorganization from Japan Hackathon: https://github.com/napari/docs/pull/881
    - [name=Melissa] Follow-up on Unversioned Pages https://github.com/napari/docs/issues/836: Blog? Scientific Python? PyData Sphinx Theme?

- New topics
    - [name=Tim] Plugin documentation
    - How to glue napari-plugin-template to napari docs
        - no global search when trying to glue different docs from different repos together
        - sphinx might update search to be something more indexable
        - Sphinx 9 is a rewrite of autodoc
        - (haha another reason for unversioned pages)
        - Melissa's suggestion do the documentation as usual on napari.org with latest deployed to latest. On those specific pages recommend going to the latest pages. Melissa will help
    - Pixi still stuck for environment markers

- Discussion: reorg
    - Quickstart vs. getting started: should we rename?
    - open images (remove "in napari")
- Navbar still going to two rows on smaller screens. https://github.com/napari/napari-sphinx-theme/issues/200
    - its been tried, but maybe we can set a height maximum for the navbar, rathe than a width. in order to snap to hamburger
- 

## 2025-11-20/21

### Attendees

- Draga, Tim, Carolyn Brokowski, Melissa

### Topics

- Introductions :)
    - Carolyn - background in acute care medicine. in a bioengineering PhD program. in a course about contributing to open source
- Check over the new contributing documentation guide https://napari.org/dev/developers/contributing/documentation/index.html
    - collapse by default the advanced make dropdown
    - make the dropdown header thing a little bigger, but don't add a header
- Discuss the great blog post and review quantixed experience in https://github.com/napari/docs/issues/886 (Tim partly needs an excuse to sit down and do this)
    - `conda create -y -n napari-env -c conda-forge napari pyqt`
    - GIVE ONE SET OF INSTRUCTIONS?!?, then have advanced options later
    - how we recommend using napari
    - philosophy in docs is that every page is PAGE ONE. Therefore, every page you access is the starter page
    - quickstart guide contains information, but they went to "using the tracks layer"
    - consider how to add a "how to run a python script" guide
- Discuss improvements to installation / getting started guides
- [name=Tim] Improving the installation guide, prompted by many discussions at in person events this year, as well as issues like [napari/docs#886](https://github.com/napari/docs/issues/886)
    - [name=Melissa] Let's also include https://github.com/napari/docs/issues/769
- [name=Melissa] Proposal for reorganization from Japan Hackathon: https://github.com/napari/docs/pull/881
    - Melissa's goal is unrolling some of the docs
    - Quickstart now top level
    - Layers at a glance needs a new name
    - Open Images in napari -- maybe add Save to this as well?
    - Feature Highlights top left
    - Cards at the top to quick link down to the App installation method
        - Be very clear, maybe in the headers, that layers are ways to use data in napari
    - Consider how to reorganize How-Tos, move things to top level
    - 
    - "earthbound theme for VSCode"
- [name=Melissa] Follow-up on Unversioned Pages https://github.com/napari/docs/issues/836: Blog? Scientific Python? PyData Sphinx Theme?

### Action Items:

- Tim: reply to napari/docs#886

## 2025-10-09/10

### Attendees

Juan, Draga, Tim, Grzegorz

### Topics

- remove unversioned workflow!
- review https://github.com/napari/docs/pull/864
- docs for hackathon
    - more scientific things - so full use case in the docs
- napari-lattice -- very behind on napari versions, aicsimageio
- napari-empanada -- pinned to 0.4.18
- CircleCI will now do shallow checkout instead of full checkout
- npe2api needs to switch from vercel (where we call it a hobby project) to netlify (where we have can open source plan)

## 2025-09-25/26

### Attendees

Carol, Peter, Melissa, Draga, Tim

### Topics

- Docs build
    - ok after Peter reverted the constraints change
    - narrowed it down to likely numba + llvm
    - went through notebook that's "dying" and can't figure out why it might be
    - is it reproducible? Yes, on CI it crashes every time
    - Grzegorz is going to change the constraints build to run a full build of the docs so that in future we would catch this
    - maybe we could do separate PRs for tests & docs?
        - would mean we can use new versions of packages elsewhere and just pin docs separately
    - CW: could be a kernel issue
    - PS: seems weird that it's this notebook that's failing because it doesn't use numba
        - does use labels & points and both those layers **do** have numba code in them
        - can we isolate the cells that are causing it?
    - Need to be careful because we don't want to merge the bot PRs each week if they continue to try updating numba/llvm
        - can we restrict the versions of stuff in the notebook itself, for now e.g. just install different versions at the top?
    - Maybe the notebook could just be static?
        - nice to catch this sort of stuff though
    - Action: Peter is going to isolate which cell is causing it to fail and make it static, and then open an issue to find an actual fix
- Theme
    - almost ready to cut a release, all PRs merged
    - one draft PR is open to fix version switcher for old versions and the warning banner
    - needs to be done manually
    - hoping to fix tomorrow
    - if we do a release tomorrow, we can still update constraints
        - we just want to do it manually so the bot doesn't pick up numba/llvm stuff
    - Tim can do the manual constraints update
- Re. unversioning
    - wouldn't even worry about old versions?
    - Melissa needs to sleep at night, so no
- Docs PRs ready to merge?
    - constraints is fixed now, so we should be able to re-run CI and just merge
    - Tim is going to look at these
- Eventually revisiting the idea of an "org" section and a "docs" section that are more clearly delineated on the website
    - definitely could be useful with case studies, workshops, etc.
    - Melissa has done similar stuff for CZI while maintaining website look and feel

### Action Items
- Melissa: cut napari-sphinx-theme 1.0
- Tim: manually update constraints after
- 

## 2025-09-11/12

### Attendees

Tim, Melissa, Draga, Juan

### Topics

- Theme release
    - triaged some theme issues last docs wg
    - targetting a 1.0 release
    - Tim has a PR for dark mode
        - Juan needs a dark mode CZI logo on his funding PR
        - admonitions are kinda ugly in dark mode
        - maybe we just add a "beta" header so people know it's still a WIP
        - Melissa suggested some fixes for headings etc. that need color changes
        - there's still an issue with the "tabbed" display but haven't had a chance to check it yet, Melissa can suggest a fix if she gets a bit more time to look at it
        - need to add switcher to napari docs
- Un-customizing the sphinx theme to match pydata sphinx theme
    - would be great for maintainability
    - as it is now it's fairly stable, so maybe it's not worth doing?
    - Tim did play with ripping some stuff out and was surprised by how little things changed
        - a lot of it is spacing stuff that is not doing a lot (or even anything?)
    - now, when you edit it, you have to create the base CSS and then copy that over to different spots
        - part of it is just the cascading aspect
    - quite likely that some improvements are now default in pydata sphinx theme
    - the goal now is to have our own visual identity, **not** to match the current website pixel by pixel
- dark theme
    - looks excellent :star-struck: 
    - suggested napari purple for the dark theme
- #835 @jni https://github.com/napari/docs/pull/835
    - will make dedicated issue
- unversioned pages
    - https://github.com/napari/docs/issues/836
    - maybe we just leave an admonition for folks to look at new version on docs?
    - version switcher will probably work better after we split this out
    - JNI, Draga happy to switch to not maintaining unversioned pages, now that our release cadence is much quicker
    - need to upstream the issue and detail what we've done, because realistically it should be a pydata feature


### Action Items

- Melissa will push to theme PR to make the suggested updates
- Melissa fix the "middle stage" of the header bar when reducing width
- We cut sphinx-theme release
- Melissa will add the theme switcher to docs (after theme release)
- Tim will PR to docs for release guide
- Tim will check docs #818
- Tim will make issue to napari-release-tools for tracking the name issue in docs#835
- Melissa will fix https://github.com/napari/docs/pull/835 on napari.github.io

## 2025-08-28/29

### Attendees

Carol, Melissa, Peter, Tim

### Topics

- unversioned pages discussion
    - high maintainer burden and buggy right now, which impacts visitors to the site
    - all of us lean towards removing the feature
    - consider the approach used by other libraries that have a homepage and docs page
    - currently this requires contract worker hours to maintain, and has been a significant time sink
    - If we turn off the unversioned pages:
        - fix the banner information between versions so dev suggests stable and versions suggest stable and no banner when on stable
        - use admonitions/etc to signal where relevant (like Contributing guide)
        - ensure the contributor guide signals correctly to look at dev
- discussion about getting bot rate limited in our CI. we need to be more aggressive about caching. 
    - Melissa does not know a way to cache for sphinx-gallery
    - Consider just adding all our stuff to some kind of bucket
    - DVC is next generation of VCS
    - Cloudflare at least used to not charge for egress

- theme issues
    - font issue is resolved, closing
    - menu/nav bar glitches in intermediate state between wide and fully burger'd
        - update to the upstream theme might resolve it
    - API docs styling
        - wishlist item, hard to do. will leave open

### Action items



## 2025-08-14/15

### Attendees

Draga, Peter, Carol

### Topics

- Mystery: Keep an eye on docs and napari repos that things deploy correctly if a job is suspended.
- markdown linter/formatter: https://github.com/napari/docs/pull/54
    - looked at this PR and it probably needs to be converted into an issue and link back to the PR for discussion
    - [Issue 821](https://github.com/napari/docs/issues/821) opened, PR closed

### Action items

## 2025-07-31/2025-08-01

### Attendees

Peter, Melissa, Tim

### Topics

- [name=Peter] Version switcher errors https://github.com/napari/docs/issues/801
    - Melissa has a fix, will submit tomorrow
- [name=Peter] Bundle page installer updates are in progress, will try to finish that PR this week
- [name=Melissa] Autogeneration for videos/screenshots
    - https://github.com/napari/docs/pull/308 In a good place, may be up for review soon
- [name=Tim] Update release guide to add information about symlink update
    - https://github.com/napari/docs/issues/778
- [name=Carol] https://github.com/napari/docs/issues/809
    - Melissa will investigate
    - Revert part of [announcement banner PR](https://github.com/napari/docs/commit/b8fc6dd334615bd6e6a77bafdfc846412737b303#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3)
- Review of Sphinx vs Mkdocs
    - Sphinx can be overkill, but has everything
    - Mkdocs for new things, better development experience
    - Peter likes Quartodocs, its super simple, would not go into Sphinx for a new things
    - Docstrings -> Automate API -> 
    - Jupyter book if a bunch of notebooks https://github.com/saramcardle/FS2K/pull/1/files
    - Giving a workflow file and teach parts have to tinker
    - Build locally, but then send to main
    - https://github.com/TheJacksonLaboratory/bestpractices_workshop/blob/main/pytest.md

## 2025-07-17/18

### Attendees

Peter, Carol, Tim, Ian, Melissa

### Topics

- [name=Melissa] Discussion: FAQ page https://github.com/napari/docs/issues/493
    - we have troubleshooting, what about FAQ?
        - thumbs up to closing
    - Ian: FAQ can be useful when it's not an error
    - Potential FAQs:
        - multiscale / texture limit, big data (open issue, epic)
        - plugin contributions and how to access plugins
        - remote Jupyter (open issue, Peter)
    - Search is not great-- see https://github.com/napari/docs/issues/758 (Melissa will look into this)
        - Adam at SciPy is core dev of algolia and sphinx? I didn't take good notes... sorry Carol
- [name=willingcn] Move forward constraints PR 672 https://github.com/napari/docs/pull/672
    - Update napari/docs to use 3.12 for CI (Melissa will do)
- [name=Melissa] Community repo? https://github.com/napari/docs/issues/784
    - sprint repo that can be a template for next sprints?
    - Carol: what about "outreach" for all outward communications?
    - Tim: will summarize sprints in the SciPy sprint doc
    - Move hackmd "template" to this repo
    - napari Team hackMD -- need to archive this one and move docs ot th enew one
    - Steering Council: make "Outreach" repo
        - Have Melissa, Tim, and Draga be 'admins'
- [name=Melissa] Cheatsheets? :D 
    - https://github.com/matplotlib/cheatsheets
    - did not get to this
- [name=Melissa] Autogenerating docs status update
    - https://github.com/napari/docs/pull/308
    - Autogenerate images: https://github.com/napari/docs/pull/621
    - autogenerate videos by recording screen locations and using them for pyqutogui with pynput and more
- [name=Melissa] Un-collapse sidebar https://github.com/napari/docs/issues/770
- [name=Peter] Installation instruction changes per Harry at SciPy
    - job #1 is getting people to install stuff
    - split the bundle changes off, the bundle page is easy to update
    - changes to the main install page are going to be controversial if they reduce prominance of Python
    - consider overall simplification of the instrutions
- [name=Ian] Updating Events Reference https://github.com/napari/docs/issues/785
    - what is comprehensive?
        - public API? Qt
    - Carol: public first, then consider Qt/vispy
    - they are autogenerated, fixing that may be hard, but can manually add

------

At the end of the meeting:
- Copy the contents of this document to a new file in https://github.com/napari/meeting-notes/new/main/2025/working-groups/documentation
- Clear out the Agenda from last meeting
