Enhance documentation build process with pixi integration and Windows…

.gitignore

@@ -159,4 +159,9 @@ docs/plugins/_npe2_*.md
 npe2/
 
 # autogenerated fallback videos
-docs/_static/images/*.mp4
+docs/_static/images/*.mp4
+
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+pixi.lock

Makefile

@@ -15,17 +15,29 @@ docs_dir := $(current_dir)docs
 clean:
 	echo clean
 	echo $(current_dir)
+ifeq ($(OS),Windows_NT)
+	@python -c "import shutil, pathlib, glob; shutil.rmtree('$(docs_dir)/_build', ignore_errors=True); [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/api/napari*.rst')]"
+else
 	rm -rf $(docs_dir)/_build/
 	rm -rf $(docs_dir)/api/napari*.rst
+endif
 
 clean-prep: clean
+ifeq ($(OS),Windows_NT)
+	@python -c "import pathlib, glob; pathlib.Path('$(docs_dir)/guides/preferences.md').unlink(missing_ok=True); [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/developers/architecture/ui_sections/*ui.md')]; [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/plugins/_npe2*.md')]"
+else
 	rm -rf $(docs_dir)/guides/preferences.md
 	rm -rf $(docs_dir)/developers/architecture/ui_sections/*ui.md
 	rm -rf $(doc_dir)/plugins/_npe2*.md
+endif
 
 clean-gallery:
+ifeq ($(OS),Windows_NT)
+	@python -c "import shutil, pathlib; [pathlib.Path(f).unlink(missing_ok=True) for f in pathlib.Path('$(docs_dir)/gallery').glob('*') if f.is_file()]; shutil.rmtree('$(docs_dir)/_tags', ignore_errors=True)"
+else
 	rm -rf $(docs_dir)/gallery/*
 	rm -rf $(docs_dir)/_tags
+endif
 
 clean-full: clean-prep clean-gallery
 
@@ -101,16 +113,27 @@ docs-live: prep-stubs
 # no notebook execution, no generation from prep_docs, no gallery
 # will note remove existing gallery files
 slim: clean prep-stubs
+ifeq ($(OS),Windows_NT)
+	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
+else
 	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
+endif
 
 # slim, but uses -j auto to parallelize the build
 slimfast: clean prep-stubs
+ifeq ($(OS),Windows_NT)
+	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) -j auto $(SPHINXOPTS)
+else
 	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) -j auto $(SPHINXOPTS)
+endif
 
 # slimfast, but uses sphinx-autobuild to rebuild changed files
 # this will run an initial build, because it's fast
 # will not remove existing gallery files
 slimfast-live: clean prep-stubs
+ifeq ($(OS),Windows_NT)
+	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --open-browser --port=0 -j auto $(SPHINXOPTS)
+else
 	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
 	sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 \
 	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
@@ -121,6 +144,7 @@ slimfast-live: clean prep-stubs
 	--open-browser \
 	--port=0 \
 	-j auto $(SPHINXOPTS)
+endif
 
 # slim, but with all gallery examples
 # does not remove existing gallery files

README.md

@@ -15,6 +15,9 @@ Alternatively, our CI setup provides a preview link that shows your changes.
 Please read our [contributing guide](https://napari.org/dev/developers/contributing/documentation/index.html) for more comprehensive information about contributing documentation.
 
 ### quickstart: local setup
+
+#### Option 1: Manual setup
+
 * __Check the prerequisites__
     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](https://packaging.python.org/en/latest/specifications/dependency-groups/) 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]" --group docs` from your `napari/napari` clone directory. This will use the default Qt backend.
@@ -32,6 +35,67 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut
 These steps should set you up to build and preview your docs contributions on your local machine.
 For more detailed instructions and tips, please visit the relevant sections of our [contribution guide](https://napari.org/dev/developers/contributing/documentation/index.html).
 
+#### Option 2: Using pixi (for slimfast builds only)
+
+[Pixi](https://pixi.sh) provides a simple, cross-platform way to quickly build the documentation using the `slimfast` target without manually installing dependencies or cloning the napari source repository.
+
+**Note: This option only supports `make slimfast` builds, and it will clone the main napari repo from the main branch on GitHub into the pixi environment. For docstring changes, full builds with the gallery (`make html`), or other build options, use Option 1.**
+
+1. **Install pixi** (if not already installed):
+   ```bash
+   # Windows (PowerShell)
+   iwr -useb https://pixi.sh/install.ps1 | iex
+
+   # macOS/Linux
+   curl -fsSL https://pixi.sh/install.sh | bash
+   ```
+
+   **Important:** After installation, you need to add pixi to your PATH:
+
+   - **Windows**: Restart your PowerShell terminal, or run:
+     ```powershell
+     $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+     ```
+
+   - **macOS/Linux**: Restart your terminal, or run:
+     ```bash
+     # For bash
+     source ~/.bashrc
+
+     # For zsh (macOS default since version 10.15 Catalina)
+     source ~/.zshrc
+
+     # For fish shell
+     fish_add_path ~/.pixi/bin
+     ```
+
+     **Note:** If you're using fish shell and pixi was just installed, you may need to manually add it to your PATH with the command above.
+
+   Verify pixi is available by running: `pixi --version`
+
+2. **Clone this repository**:
+   ```bash
+   git clone https://github.com/napari/docs.git napari-docs
+   cd napari-docs
+   ```
+
+3. **Install dependencies** (should automatically run for your platform):
+   ```bash
+   pixi install
+   ```
+
+4. **Build the docs** (slimfast only):
+   ```bash
+   pixi run slimfast
+   ```
+
+5. **Preview**: Open `docs/_build/html/index.html` in your browser.
+
+**Notes:**
+- The `pixi.toml` is multi-platform; no manual platform selection is required and it should “just work” on Windows, Linux, and macOS.
+- If you update pixi, run `pixi install` again to refresh the environment.
+- The Makefile includes cross-platform support, so builds work consistently across platforms.
+
 ## code of conduct
 
 `napari` has a [Code of Conduct](https://napari.org/community/code_of_conduct.html) that should be honored by everyone who participates in the `napari` community.

pixi.toml

@@ -0,0 +1,18 @@
+
+[workspace]
+authors = ["napari developers"]
+channels = ["conda-forge"]
+name = "napari-docs"
+
+platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]  # All platforms
+version = "0.1.0"
+
+[dependencies]
+python = "3.13.*"
+make = "*"
+
+[pypi-dependencies]
+napari = { git = "https://github.com/napari/napari.git", branch = "main", extras = ["dev", "pyqt", "docs"] }
+
+[tasks]
+slimfast = "make slimfast"