napari · jni · Mar 11, 2025 · Feb 28, 2025 · Feb 28, 2025 · Feb 28, 2025
diff --git a/Makefile b/Makefile
@@ -20,10 +20,6 @@ clean:
 	rm -rf $(docs_dir)/gallery/*
 	rm -rf $(docs_dir)/_tags
 
-docs-install:
-	python -m pip install -qr $(current_dir)requirements.txt
-	python -m pip freeze
-
 prep-docs:
 	python $(docs_dir)/_scripts/prep_docs.py
 
@@ -33,8 +29,6 @@ docs-build: prep-docs
 docs-xvfb: prep-docs
 	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 xvfb-run --auto-servernum sphinx-build -M html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
 
-docs: clean docs-install docs-build
-
 html: clean docs-build
 
 # Implies noplot, but no clean - call 'make clean' manually if needed

diff --git a/README.md b/README.md
@@ -16,15 +16,14 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut
 
 ### quickstart: local setup
 * __Check the prerequisites__
-    1. Create a clean Python environment (e.g., with conda).
-    1. In that environment, create a [development installation](https://napari.org/dev/developers/contributing/dev_install.html#dev-installation) of `napari` on your local machine, first forking and cloning the main `napari` project if you've not previously done so.
-    1. Fork this repository, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`.
-    1. With your local clone's root folder as the working directory, and with the environment created in the first step activated, install the docs requirements with `python -m pip install -r requirements.txt`.
+    1. Create a clean Python (>=3.10) environment (e.g., with conda).
+    1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e ".[pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend.
+    1. Fork *this* repository, `napari/docs`, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`.
 * __Build__ locally
     * If you're building on Windows, a few extra steps are required; you can follow [this guide](https://napari.org/dev/developers/contributing/documentation/index.html#building-the-documentation-on-windows).
     * From the root of your local clone of this repository, run one of these:
-        * `make docs`, if your changes include the example gallery
-        * `make docs-install && make html-noplot`, otherwise
+        * `make html`, if your changes include the example gallery
+        * `make html-noplot`, otherwise
 * __Preview__ locally, either dragging-and-dropping `docs/_build/index.html` into a browser, or deploying a local server with `python3 -m http.server --directory docs/_build`.
 
 These steps should set you up to build and preview your docs contributions on your local machine.

diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md
@@ -28,6 +28,7 @@ This is documentation is written with [Jinja](https://jinja.palletsprojects.com/
 5. The [API reference documentation](api) is autogenerated from the napari source code docstrings.
 Docstrings are written in the [reStructuredText format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
 and any modifications to them should be submitted to the [napari/napari](https://github.com/napari/napari) repository.
+6. Importantly, all of the dependencies for building the documentation are in the [the `pyproject.toml` of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependencies `docs` and `gallery`.
 
 (contributing-without-local-setup)=
 ## Contributing to the napari documentation without a local setup
@@ -64,7 +65,7 @@ For example, `C:\Users\myusername\Documents\GitHub\napari-docs` is a valid path,
 ```
 
 You should first [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
-and then clone the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repositories to your
+and then clone both the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repositories to your
 machine. To clone these repositories, you can follow any of the options in the [GitHub guide to cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) (if you run into issues refer to [the troubleshooting guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors)).
 We recommend installing the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) as it is easy to set up repository access permissions from the GitHub CLI and it comes with additional upside, such as the ability to checkout pull requests.
 After installing the `GitHub CLI` you can run:
@@ -80,19 +81,33 @@ a local repository folder named `napari-docs`. Alternately, you could also
 rename the repository when forking `napari/docs` to `napari-docs` and then clone it via `gh repo clone <your-username>/napari-docs`.
 ````
 
-Next, navigate to your local clone of the `napari/docs` repository:
+Next, navigate to your local clone of the `napari/napari` repository:
 
 ```bash
-cd napari-docs/
+cd napari
 ```
 
-Since the API reference documentation (autogenerated from the napari code docstrings) and the example gallery are sourced from the `napari/napari` repository, before you can build the documentation locally, you need:
+Because the API reference documentation (autogenerated from the napari code docstrings), the example gallery, and the documentation dependencies are sourced from the `napari/napari` repository, before you can build the documentation locally you will need to install from the `napari/napari` repository. You will need:
 
-- a clean `conda` environment;
-- a development installation of napari in that environment. Follow the [contributor guide](dev-installation) for details on how to do this;
-- the napari documentation requirements. Starting at the folder where you cloned the `napari/docs` repository, and after activating your clean `conda` environment, you can install these with `python -m pip install -r requirements.txt`.
+- a clean virtual environment (e.g. `conda`)  with Python {{ python_version_range }}—remember to activate it!;
+- a from-source, editable installation of napari with the optional `docs` dependencies and a Qt backend. From the `napari/napari` repository directory run, for example:
 
-This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. It will also install [Jupyter notebook](https://jupyter.org/) and [jupytext](https://jupytext.readthedocs.io), which you will need to contribute documents containing code or viewer interactions.
+      ```bash
+  python -m pip install -e ".[pyqt, docs]"
+  ```
+  This will use the default Qt backend. For other options, see [the napari installation guide](../../../tutorials/fundamentals/installation.md#choosing-a-different-qt-backend).
+
+  ````{note}
+  You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`.
+  ````
+
+Once the installation is complete, you can proceed to the directory where you cloned the `napari/docs` repository:
+
+```bash
+cd ../napari-docs
+```
+
+ Here you will be able to build the documentation, allowing you to preview your document locally as it would appear on `napari.org`.
 
 ## 0. Before you start
 
@@ -165,10 +180,7 @@ Jupyter notebook, or in your preferred text editor.
 ```{admonition} Already have a notebook?
 :class: tip
 
-If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown
-and then edit the `.md` file to prepare it for contributing.
-
-Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file,
+If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown and then edit the `.md` file to prepare it for contributing. For the conversion, you can install the [`jupytext` package](https://jupytext.readthedocs.io/en/latest/). Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file,
 `your-notebook.md`. Edit this file to include the relevant sections from the docs template.
 ```
 
@@ -280,20 +292,19 @@ To see the markdown document structure and content change in real-time without b
 
 ### 3.1. Building locally
 
-To build the documentation locally from scratch, run `make docs` from the root
+To build the documentation locally from scratch, run `make html` from the root
 of your local clone of the `napari/docs` repository (assuming you've installed
-the [docs prerequisites](prerequisites)).
+napari with the [docs prerequisites](prerequisites)).
 
 ```bash
-make docs
+make html
 ```
 
 If the changes you have made to documentation don't involve changing the napari gallery,
 you can speed up this build by running `make html-noplot` instead. This will skip the
 gallery build, which involves launching up napari and rendering all the examples.
 
 ```bash
-make docs-install  # only needed the first time
 make html-noplot
 ```
 
@@ -307,13 +318,13 @@ $ python3 -m http.server --directory docs/_build/html
 ```
 
 ````{note}
-The `make docs` command above assumes you have a local clone of the
+The `make html` command above assumes you have a local clone of the
 [`napari/napari`](https://github.com/napari/napari) repo at the same level as
 the `napari/docs` clone. If that's not the case, you can specify the location of
 the examples gallery folder by executing
 
 ```bash
-make docs GALLERY_PATH=<path-to-examples-folder>
+make html GALLERY_PATH=<path-to-examples-folder>
 ```
 
 The `GALLERY_PATH` option must be given relative to the `docs` folder. If your
@@ -333,7 +344,7 @@ folder structure is
 
 Then the command would be
 ```bash
-make docs GALLERY_PATH=../../napari/examples
+make html GALLERY_PATH=../../napari/examples
 ```
 
 ````
@@ -467,7 +478,7 @@ Then install Git Bash and build the documentation:
 2. Activate your virtual environment in Git Bash.
     - Conda environment: To have your conda environment available in Git Bash, launch Git Bash, then run `conda init bash` from anaconda prompt and restart Git Bash. The conda environment can then be activated from Git Bash with `conda activate <env_name>`.
     - Virtualenv: To have your virtualenv available in Git Bash, launch Git Bash, then run `source <path_to_virtualenv>/Scripts/activate`.
-3. From Git Bash, `cd` to the napari docs repository and run `make docs` or other `make` commands to build the documentation.
+3. From Git Bash, `cd` to the napari docs repository and run `make html` or other `make` commands to build the documentation.
 
 ```{tip}
 If you use Git Bash a lot, you may want to set conda to not initialize on bash by default to speed up the launch process. This can be done with `conda config --set auto_activate_base false`. You can then activate conda in Git Bash with `conda activate base`.
@@ -497,7 +508,7 @@ We will use Ubuntu for this guide since it is the default WSL distribution, easy
 8. `pip install pyqt5-tools`.
 9. Fork the napari docs repository and clone it to the same parent folder as the napari repository (see [](prerequisites)). Then navigate to the napari docs folder via `cd napari-docs`.
 10. Install `make` with `sudo apt install make`.
-11. Run `make docs` or other `make` commands to build the documentation.
+11. Run `make html` or other `make` commands to build the documentation.
 
 ````{admonition} Route graphical output to Windows
 :class: tip
@@ -578,6 +589,8 @@ Because our example gallery is built from Python scripts, you need to ensure thi
 block is present in all contributed examples.
 ````
 
+Finally, you can find the current example dependencies in [the `pyproject.toml` of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependency `gallery`. If you add an example with a new dependency, be sure to include it here such that your example can be properly tested and built into the documentation.
+
 ### Cross-referencing Gallery examples
 
 If you want to generate links to Gallery examples from anywhere in the docs, then the cross-referencing format you use will depend on the format of the doc you are writing. Note that the gallery examples live in `/gallery` despite being in `napari/examples` because [`docs/docs/conf.py`](https://github.com/napari/docs/blob/main/docs/conf.py) specifies that examples are built into the `gallery` directory. The [Sphinx cross-reference namespace](https://sphinx-gallery.github.io/stable/advanced.html#know-your-gallery-files) is generated with the `sphx_glr` prefix, then path separators are converted to underscores, for example `/gallery/add_image.py` becomes `_gallery_add_image.py` to get the end result `sphx_glr_gallery_add_image.py`. 

diff --git a/requirements.txt b/requirements.txt