Enhance documentation build process with pixi integration and Windows… #876
Conversation
There was a problem hiding this comment.
Thank you @rensutheart !
@jaimergp would you mind taking a look?
…form pixi.toml works out of the box
…d platform support
… latest pixi README changes
Co-authored-by: Melissa Weber Mendonça <[email protected]>
|
I think we should merge this as-is, since it does not remove any options from the docs building process, but just adds a new alternative. Since it is still incomplete, I propose we follow-up with
|
|
The convo was closed above, but adding |
|
@rensutheart Nice work! @melissawm and team, |
Co-authored-by: Carol Willing <[email protected]>
There was a problem hiding this comment.
This is AMAZING 🤩
I tested on Windows. As we can see in contributing docs, Windows is a flipping pain https://napari.org/stable/developers/contributing/documentation/index.html#building-the-documentation-on-windows
As a follow-up (or as part of this PR) we need to update this documentation page, along with the README like in this file.
I have tested this on Windows, where I have lots of experience. For example, with current make commands
cmd(the "older" Windows default terminal) -- doesn't workpowershell(the older Windows terminal that was never defualt -- doens't workpwsh(newest version of Powershell, which is some user's default) -- works (due to Unix command interoperability
NOW with this PR, pixi run {build} works flawlessly in all these situations.
The other follow-up we will need to consider for switching to pixi is whether or not to ship a lock file. These lock files, in my expeirence, aren't the easiest to build cross platform, mostly due to Qt, but it is possible. When doing pixi install initially the creation of the lock file creates much longer than I would like.
However, I'd also like to reinforce how much better this workflow is than the previous one. When testing I did the only way and didn't have a docs install, so I had to cd out, pip install -e .[docs] in napari, and then cd back, and then do it. 🤮 🤮 🤮
This is so much better!
|
@melissawm Let's land this now so folks can use at the hackathon 😄 |
|
Hoooooooraaaaaaaaaaaaaaaaaaay! Congrats on your first PR! 🥳 🎈 🎉 🤩
|
# References and relevant issues Supersedes #876, which served as a proof of concept for Windows support in `slimfast` builds. This PR extends that work to provide full cross-platform support for **all** build targets and Makefile commands. # Description This PR expands the `pixi` implementation to support **all** `make` commands on **all** platforms, specifically adding full Windows support. The previous implementation (#876, #870) only supported `slimfast` builds. With these changes, WSL is no longer required for Windows users to build the napari documentation. ## Key Changes ### 1. **Cross-Platform Makefile Support and Expanded pixi.toml File** Added Windows compatibility to all Makefile targets by detecting the OS and adjusting command syntax accordingly: - **Supported targets** - All commonly-used documentation build targets now work cross-platform: - **Cleaning**: `clean`, `clean-prep`, `clean-gallery`, `clean-full` - Modified to use Python `shutil.rmtree()` instead of `rm -rf` - **Preparation**: `prep-docs`, `prep-stubs` - Pure Python scripts, now fully cross-platform - **Full builds**: `html`, `docs-build`, `html-noplot`, `docs`, `docs-live` - Added Windows conditionals for environment variables - **Slim builds**: `slim`, `slimfast`, `slimfast-live` - Added Windows conditionals for environment variables - **Gallery builds**: `slimgallery`, `slimgallery-live` - Added Windows conditionals for environment variables - **Live previews**: `html-noplot-live` - Added Windows conditionals for environment variables - **Example builds**: `build-specific-example`, `build-specific-example-live` - Added Windows conditionals for environment variables - **Utilities**: `linkcheck-files`, `spellcheck` - Cross-platform support added/verified All tasks are now accessible via `pixi run <task-name>` and work cross-platform. - **Platform-specific handling**: Windows uses `set VAR=value&& command` syntax while Unix uses `VAR=value command`, implemented via `ifeq ($(OS),Windows_NT)` conditionals - **Unsupported targets** - Some specialized targets remain Linux/macOS only: - `docs-xvfb` and `docs-xwfb` - Display error messages on Windows (X11/Wayland specific) - `fallback-videos` and `fallback-videos-clean` - Use bash-specific shell syntax and ffmpeg (not commonly used) - **Bug fix**: Fixed typo in `clean-prep` target (`doc_dir` → `docs_dir`) ### 2. **Platform-Agnostic prep_docs.py** Replaced Unix-only shell commands with cross-platform Python equivalents: - **File deletion**: Changed from `rm -rf` to `shutil.rmtree()` with custom error handler - **Windows read-only files**: Added `_handle_remove_readonly()` function to handle Windows file permission issues - **⚠️ Behavior change**: The `prep_npe2()` function now **always deletes** the `npe2/` directory before cloning, rather than keeping it if it exists. This ensures a clean state on every build but may be slower if running multiple builds in succession. (The commented-out early return shows where to re-enable caching if desired for manual edits.) ### 3. **Updated README** - Added examples for multiple build types (similar to Option 1): - `pixi run slimfast` - recommended for development - `pixi run html` - full build with gallery - `pixi run html-noplot` - full build without gallery - `pixi run slimfast-live` - auto-rebuild variant - Added note about `make` requirement for `pixi` - Clarified multi-platform support (Windows, Linux, macOS Intel/Apple Silicon) - Added `pixi run clean` example - Added `pixi task list` reference for discovering more build options ## Testing I have manually tested several of the main commands with `pixi` under both Windows and Linux (WSL), however due to time constraints, not all `pixi` tasks were tested and I could not test on macOS, but the Makefile conditionals follow established patterns and should work correctly. ## Impact This PR makes napari documentation building significantly more accessible: 1. **Windows users** can now build full documentation without WSL 2. **All users** can use `pixi` for a simplified, dependency-managed build process 3. **Contributors** have more flexibility in choosing their build workflow (Option 1 manual setup vs Option 2 pixi automation) 4. **Cross-platform consistency** is improved with standardized environment variable handling ## Notes for Reviewers - The `npe2/` directory deletion behavior change in `prep_docs.py` is intentional for consistency, but the early return can be re-enabled if caching is preferred (see commented code) - All Windows-specific Makefile changes use `set VAR=value&&` with no space before `&&` (PowerShell requirement) - Consider testing on Linux/macOS to verify cross-platform functionality before merging --- **Final Checklist:** - [x] My PR is the minimum possible work for the desired functionality - [x] I have added comments to explain complex changes (Windows file handling) - [x] Documentation (README) has been updated to reflect new capabilities - [x] Cross-platform compatibility has been considered and implemented --------- Co-authored-by: Melissa Weber Mendonça <[email protected]> Co-authored-by: Carol Willing <[email protected]>
6 participants
References and relevant issues
Supersedes #870
N/A for issues (no behavior change to deployed docs; optional local build support only)
Description
This PR adds an optional pixi-based setup to build the documentation using the existing Makefile targets—specifically the fast, no-gallery path—without requiring a local clone or editable install of the napari source.
What’s included
Add a minimal pixi.toml so contributors can run
pixi run slimfastto build docs quickly.Pin Python to 3.13 to align with feedback on #870.
Reuse the Makefile as the source of truth (tasks.slimfast = "make slimfast"); no custom commands or duplicated logic.
Document a simple “Option 2: Using pixi” flow in README.md for cross‑platform slim builds.
Scope and intent
This is intentionally narrow: it only supports the slimfast build (docs repo content only; no gallery; no notebook cell execution).
Nothing changes if you don’t want to use pixi; the standard manual path remains the default and supports full builds.
The pixi.toml is kept single‑platform to avoid lock inconsistencies; users switch the platforms = [""] entry before pixi install.
Why supersede #870
Incorporates reviewer suggestion to use Python 3.13 rather than a version range.
Keeps risk and surface area low by delegating to the existing Makefile targets instead of introducing new workflows.
Provides clear, minimal documentation for contributors who prefer pixi for a quick local preview.
Final checklist
Minimal changes for desired functionality
Uses existing Makefile targets; consistent with current CI and local builds
Optional path only; no changes to deployed docs behavior