# 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