Refactor contributor docs: prioritize pixi for local builds

[rensutheart]

Summary

This PR refactors the documentation contributor guide, completing the transition to pixi as the recommended cross-platform workflow for building the napari docs. The guide now highlights a simple pixi-based path for most contributors, while still preserving the full make workflow for advanced and headless use cases.

Key Changes

• Pixi-first workflow

  • Recommends pixi as the default way to build the docs on Windows, macOS, and Linux.
  • Documents setup, common build targets (pixi run slimfast, pixi run html, pixi run html-noplot, etc.), and troubleshooting.
  • Notes that pixi automatically manages dependencies and clones napari/napari internally.

• Reorganized contributor flow

  • For most contributions, users now only need to fork and clone napari/docs.
  • Editing napari/napari (e.g. gallery examples or API docstrings) is described separately and clearly marked as optional.

• Advanced make workflow retained

  • All make instructions (including partial builds, gallery-only builds, live rebuild targets, cleanup utilities, etc.) are preserved under an “Advanced: Using make” dropdown.
  • Windows guidance for make (Git Bash / WSL setup, path safety, etc.) is still available, but no longer blocks the main path. It has also been shortened substantially as it is generally not needed anymore.

• Windows experience clarified

  • States clearly that pixi runs natively on Windows in PowerShell/CMD.
  • Positions Git Bash and WSL as optional alternatives, not requirements.

Why These Changes?

• Follows through on the work started in Pixi cross platform support #879, which added cross-platform pixi support to the Makefile and build system.
• Lowers the barrier for first-time contributors, especially on Windows (no WSL, no manual conda/Qt setup required for most edits).
• Keeps advanced users unblocked by preserving the full make flow, including headless / gallery-specific / single-example builds.
• Reduces setup errors by making pixi the default, dependency-managed path.

Testing

• Manually tested pixi run targets (slimfast, html, html-noplot, live targets, cleanup targets) on Windows and Linux.
• Confirmed that make targets documented in the advanced section still work.

Conclusion

This is an extensive change to the documentation, and I could have overlooked things or made unhelpful changes. Change suggestions welcome.

[melissawm]

Thank you so much @rensutheart, this is looking really nice!

I have some general comments about the organization of content, and haven't reviewed everything in detail. I think we can still simplify this a bit, but let's see what others think.

Cheers!

[melissawm]

I think the dropdowns are a little muted and hard to spot - what do folks think of using color instead of having them be muted gray? Here's examples from the pydata-sphinx-theme:

[rensutheart]

I have used the primary color for the advanced make option, as this might be an important one to highlight.

[psobolewskiPhD]

Out of curiosity for those that use uv a lot (@TimMonko ?): it also has project-based workflows and task running -- I think? Is it worth a followup to enable that as an alternative to pixi? at the moment, we're not using anything conda-forge specific to my knowledge (unless we decide to aadd git or make, etc.)

[melissawm]

@psobolewskiPhD can you use uv to build napari from source and chain the docs build with that? My impression is that this was not possible in a simple way (you can always activate the venv that uv creates but that kinda defeats the purpose of a task-based workflow I think)

The end goal here is to be able to do that as a one-liner, even though right now the pixi.toml file is set to track napari from github.

[psobolewskiPhD]

@melissawm I'm not very familiar with uv, I thought it also has a run option to run tasks, so I thought maybe it could work similarly. I have no idea though! Hence asking 😅

[TimMonko]

Out of curiosity for those that use uv a lot (@TimMonko ?): it also has project-based workflows and task running -- I think? Is it worth a followup to enable that as an alternative to pixi? at the moment, we're not using anything conda-forge specific to my knowledge (unless we decide to aadd git or make, etc.)

A key difference here is how uv and pixi approach this. Pixi is a cross-platform / cross-language task runner built around environment management, so you can run things like make commands without issue. In contrast, uv is pretty strictly a python env manager and python task runner by design (i.e. uv run script.py is the primary task running pattern). So, if you want to run the docs build through a python script, it would work, but I'm pretty sure that's a bad idea (because people don't do that).

So in the end the major difference is that uv is for python and pixi is for python+

[TimMonko]

Also, thanks for the awesome PR @rensutheart . I support these changes in general. Since other folks are reviewing, I'll let that be the case for now, but do ping me if you want me to look at things.
Really appreciate all the hard work you put in for the hackathon 🔥

[psobolewskiPhD]

Thanks for the explanation @TimMonko I'm a pixi fan, but wanted to throw a bone to the uv fans!
I guess in this sort of case, pixi is the way to go!